Voltagent Core Reference

What Is This?

Overview

VoltAgent Core Reference is the authoritative technical guide for the VoltAgent class found in the @voltagent/core package. It covers constructor options, lifecycle methods, and runtime behavior that developers need to build, configure, and manage AI-powered agents in TypeScript and JavaScript environments. The reference draws directly from the source files packages/core/src/voltagent.ts and packages/core/src/types.ts, making it the most accurate and up-to-date resource for working with the framework.

The VoltAgent class serves as the central orchestration layer for agent-based applications. It accepts a structured options object (VoltAgentOptions) at instantiation, exposes lifecycle hooks for initialization and teardown, and governs how agents behave at runtime. Understanding this class is essential for anyone building production-grade AI workflows on the VoltAgent platform.

This reference is distributed under the MIT license and maintained by the VoltAgent team in the official skills repository at https://github.com/VoltAgent/skills. It is versioned alongside the core package to ensure consistency between documentation and implementation.

Who Should Use This

• Backend developers building AI agent pipelines who need precise control over constructor configuration and runtime options.
• TypeScript engineers who require type-safe integration with VoltAgentOptions and related interfaces from types.ts.
• Platform architects designing multi-agent systems who need to understand lifecycle sequencing and agent coordination.
• DevOps and infrastructure engineers responsible for deploying and monitoring VoltAgent instances in production environments.
• Open-source contributors working on the @voltagent/core package who need a reliable reference for existing behavior before submitting changes.
• Technical leads evaluating VoltAgent for adoption and requiring a complete picture of the core API surface.

Why Use It?

Problems It Solves

• Eliminates guesswork when configuring the VoltAgent constructor by providing a complete breakdown of all supported options and their default values.
• Reduces debugging time by clarifying the order and behavior of lifecycle methods, which is critical when agents fail silently during initialization or shutdown.
• Prevents misconfiguration in production by documenting runtime constraints and expected input shapes for VoltAgentOptions.
• Bridges the gap between source code and practical usage, so developers do not need to read raw TypeScript source files to understand the API.
• Supports consistent team onboarding by providing a single, canonical reference that all developers can consult.

Core Highlights

• Full documentation of the VoltAgentOptions interface and all supported configuration keys.
• Lifecycle method reference covering initialization, execution, and teardown phases.
• Runtime behavior documentation explaining how the agent processes inputs and manages state.
• Direct traceability to source files voltagent.ts and types.ts for verification.
• MIT-licensed content suitable for use in internal wikis, team documentation, and public projects.
• Version-pinned to 1.0.0 for stability in production dependency chains.
• Compatible with the broader VoltAgent skills ecosystem for modular knowledge reuse.

How to Use It?

Basic Usage

Install the core package and instantiate the VoltAgent class with a configuration object:

import { VoltAgent } from "@voltagent/core";

const agent = new VoltAgent({
  name: "my-agent",
  model: "gpt-4o",
  instructions: "You are a helpful assistant.",
});

await agent.start();

Specific Scenarios

Scenario 1: Custom lifecycle hooks

Attach handlers to lifecycle events to log agent activity or perform cleanup:

const agent = new VoltAgent({
  name: "monitored-agent",
  model: "gpt-4o",
  onStart: () => console.log("Agent started"),
  onStop: () => console.log("Agent stopped"),
});

Scenario 2: Runtime configuration override

Pass runtime options at execution time to override defaults set during construction:

const response = await agent.run("Summarize this document.", {
  temperature: 0.3,
  maxTokens: 512,
});

Real-World Examples

• A customer support platform uses VoltAgent with custom onStart hooks to register agents in a central service registry on boot.
• A data pipeline team configures maxTokens and temperature at runtime to control output verbosity depending on the task type.
• A multi-tenant SaaS product instantiates separate VoltAgent instances per tenant, each with isolated configuration and lifecycle tracking.

When to Use It?

Use Cases

• Configuring a new VoltAgent instance for a production deployment.
• Debugging unexpected agent behavior by reviewing lifecycle method documentation.
• Auditing constructor options to ensure compliance with internal security or configuration policies.
• Onboarding new team members who need a structured introduction to the core API.
• Writing integration tests that mock or stub lifecycle methods.
• Evaluating VoltAgent against other frameworks based on API design and runtime flexibility.
• Contributing new features or bug fixes to the @voltagent/core package.

Important Notes

Requirements

• Node.js 18 or higher is required to run @voltagent/core.
• TypeScript 5.0 or higher is recommended for full type inference with VoltAgentOptions.
• A valid API key for the configured LLM provider must be available in the runtime environment.
• The @voltagent/core package must be installed at version 1.0.0 or later to match this reference.