VoltAgent

https://voltagent.dev/docs/
Admin
VoltAgent is an open source TypeScript framework for building production-ready AI agents with...
Tokens:462,268
Snippets:3,490
Trust Score:8.7
Update:15 hours ago
Show doc for...
Tokens:
Raw
### Quick Start: Create and run with-chat-sdk example

Source: https://voltagent.dev/docs/integrations/chat-sdk/

Commands to scaffold the example project, install dependencies, and start the dev server. Requires environment variables: OPENAI_API_KEY, SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, and REDIS_URL.

```bash
npm create voltagent-app@latest -- --example with-chat-sdk
cd with-chat-sdk
pnpm install
pnpm dev
```

--------------------------------

### Pinecone Vector Database Setup

Source: https://voltagent.dev/docs/rag/overview/

Create a VoltAgent app with the with-pinecone example. No setup needed; just get an API key.

```bash
# No setup needed - fully managed service
# Just get your API key and run

npm create voltagent-app@latest -- --example with-pinecone
```

--------------------------------

### Chroma Vector Database Setup

Source: https://voltagent.dev/docs/rag/overview/

Start a local Chroma server and create a VoltAgent app with the with-chroma example. Requires Docker for local Chroma.

```bash
# Start Chroma server
npm run chroma run

# Try the example
npm create voltagent-app@latest -- --example with-chroma
```

--------------------------------

### Create example project with npm create voltagent-app

Source: https://voltagent.dev/docs/rag/voltagent/

Run this command to scaffold a new VoltAgent project with the 'with-voltops-retrieval' example. The example includes VoltAgentRagRetriever setup, automatic and tool-based patterns, memory integration with LibSQL, and a Hono server for API endpoints.

```bash
npm create voltagent-app@latest -- --example with-voltops-retrieval
```

--------------------------------

### Set up and run documentation site

Source: https://voltagent.dev/docs/community/contributing/

Navigate to the website directory, install dependencies with npm, and start the Docusaurus development server.

```sh
cd website
npm install
npm start
```

--------------------------------

### Server setup before (0.1.x) with built-in server

Source: https://voltagent.dev/docs/getting-started/migration-guide/

In VoltAgent 0.1.x, the server was built into @voltagent/core and configured with port, enableSwaggerUI, and autoStart options. This example shows the old setup before migration.

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

new VoltAgent({
  agents: { agent },
  port: 3141,
  enableSwaggerUI: true,
  // server auto-started
});
```

--------------------------------

### Update to 1.x: Replace VercelAIProvider with Memory and honoServer

Source: https://voltagent.dev/docs/getting-started/migration-guide/

Shows the new 1.x setup: imports from @voltagent/core, @voltagent/libsql, @voltagent/server-hono, and @voltagent/logger. Removes the VercelAIProvider import and llm option, adds Memory with LibSQLMemoryAdapter, and passes honoServer() to VoltAgent. Keep your existing logger setup or use the example.

```typescript
// REMOVE (0.1.x):
// import { VercelAIProvider } from "@voltagent/vercel-ai";

import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { honoServer } from "@voltagent/server-hono";
import { createPinoLogger } from "@voltagent/logger";

const logger = createPinoLogger({ name: "my-app", level: "info" });

const memory = new Memory({
  storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});

const agent = new Agent({
  name: "my-app",
  instructions: "Helpful assistant",
  // REMOVE (0.1.x): llm: new VercelAIProvider(),
  model: "openai/gpt-4o-mini",
  memory,
});

new VoltAgent({
  agents: { agent },
  server: honoServer(),
  logger,
});
```

--------------------------------

### Qdrant Vector Database Setup

Source: https://voltagent.dev/docs/rag/overview/

Create a VoltAgent app with the with-qdrant example. Qdrant is an open-source vector search engine.

```bash
npm create voltagent-app@latest -- --example with-qdrant
```

--------------------------------

### Basic VoltAgent Setup with Hono Server

Source: https://voltagent.dev/docs/

Initializes a VoltAgent with a single agent using OpenAI's gpt-4o-mini model and a Hono server. Requires installing @voltagent/core, @voltagent/server-hono, and @ai-sdk/openai.

```typescript
import { VoltAgent, Agent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";

const agent = new Agent({
  name: "my-voltagent-app",
  instructions: "A helpful assistant that answers questions",
  model: openai("gpt-4o-mini"),
});

new VoltAgent({
  agents: { agent },
  server: honoServer(),
});
```

--------------------------------

### Install @voltagent/sandbox-daytona

Source: https://voltagent.dev/docs/workspaces/sandbox/

Install the Daytona sandbox package. It automatically pulls in @daytonaio/sdk, so no separate install is needed.

```bash
pnpm add @voltagent/sandbox-daytona
```

--------------------------------

### Install @voltagent/voice with yarn

Source: https://voltagent.dev/docs/agents/voice/

Install the package using yarn.

```bash
yarn add @voltagent/voice
```

--------------------------------

### Complete Workflow Execution Lifecycle Example

Source: https://voltagent.dev/docs/api/endpoints/workflows/

JavaScript example showing how to start a workflow, check if it is suspended, get manager approval, and resume the workflow. Uses the /workflows/order-approval/execute and /workflows/order-approval/executions/{executionId}/resume endpoints.

```javascript
// 1. Start workflow
const executeResponse = await fetch("/workflows/order-approval/execute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    input: {
      orderId: "ORD-999",
      amount: 10000,
      items: ["laptop", "monitor"],
    },
  }),
});

const execution = await executeResponse.json();
const executionId = execution.data.executionId;

// 2. Check if suspended
if (execution.data.status === "suspended") {
  console.log("Workflow suspended:", execution.data.suspension.reason);

  // 3. Get manager approval (external process)
  const approval = await getManagerApproval();

  // 4. Resume workflow
  const resumeResponse = await fetch(`/workflows/order-approval/executions/${executionId}/resume`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      resumeData: {
        approved: approval.approved,
        managerId: approval.managerId,
        comments: approval.comments,
      },
    }),
  });

  const finalResult = await resumeResponse.json();
  console.log("Final result:", finalResult.data.result);
}
```

--------------------------------

### Manual setup with explicit VoltOpsClient

Source: https://voltagent.dev/docs/agents/memory/managed-memory/

Create a Memory instance with an explicit VoltOpsClient for manual credential management.

```ts
import { Agent, Memory, VoltOpsClient } from "@voltagent/core";
import { ManagedMemoryAdapter } from "@voltagent/voltagent-memory";

const voltOpsClient = new VoltOpsClient({
  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
  // baseUrl: "https://api.voltagent.dev", // optional
});

const memory = new Memory({
  storage: new ManagedMemoryAdapter({
    databaseName: "production-memory",
    voltOpsClient, // explicit client
  }),
});

const agent = new Agent({
  name: "Assistant",
  model: "openai/gpt-4o-mini",
  memory,
});
```

--------------------------------

### Create VoltAgent project with Qdrant

Source: https://voltagent.dev/docs/rag/qdrant/

Use npm create voltagent-app@latest with the --example with-qdrant flag to scaffold a new project. Then change into the project directory.

```bash
npm create voltagent-app@latest -- --example with-qdrant
cd with-qdrant
```

--------------------------------

### Get Agent by ID - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/agents/

Example response from GET /agents/:id, showing detailed information about a specific agent.

```json
{
  "success": true,
  "data": {
    "id": "assistant",
    "name": "Assistant",
    "description": "A helpful AI assistant",
    "status": "idle",
    "model": "gpt-4o-mini",
    "tools": ["search", "calculator"],
    "subAgents": [],
    "memory": {
      "config": {}
    },
    "isTelemetryEnabled": true
  }
}
```

--------------------------------

### Complete REST API workflow streaming example in TypeScript

Source: https://voltagent.dev/docs/workflows/streaming/

This example demonstrates the full lifecycle of a workflow using the REST API: starting a streaming execution, processing the SSE stream until suspension, and resuming the workflow after approval. It uses the /workflows/{workflowId}/stream endpoint to start and the /workflows/{workflowId}/executions/{executionId}/resume endpoint to resume. The example simulates a manager approval delay and returns the final result.

```typescript
async function executeWorkflowWithREST() {
  const apiUrl = "http://localhost:3141";
  const workflowId = "expense-approval";
  let executionId: string | null = null;

  // 1. Start streaming execution
  console.log("Starting workflow stream...");
  const streamResponse = await fetch(`${apiUrl}/workflows/${workflowId}/stream`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      input: {
        employeeId: "EMP001",
        amount: 750,
        category: "travel",
        description: "Conference attendance",
      },
      options: {
        userId: "user-123",
      },
    }),
  });

  // 2. Process stream until suspension
  const reader = streamResponse.body!.getReader();
  const decoder = new TextDecoder();
  let suspended = false;

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n");

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const event = JSON.parse(line.slice(6));
        console.log(`Event: ${event.type}`);

        if (!executionId && event.executionId) {
          executionId = event.executionId;
        }

        if (event.type === "workflow-suspended") {
          suspended = true;
          console.log("Workflow suspended, stream closed");
        }
      }
    }
  }

  // 3. If suspended, resume after approval
  if (suspended && executionId) {
    console.log("Getting manager approval...");
    await new Promise((resolve) => setTimeout(resolve, 2000)); // Simulate delay

    console.log("Resuming workflow...");
    const resumeResponse = await fetch(
      `${apiUrl}/workflows/${workflowId}/executions/${executionId}/resume`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          resumeData: {
            approved: true,
            managerId: "MGR001",
            comments: "Approved for conference",
            adjustedAmount: 700,
          },
        }),
      }
    );

    const result = await resumeResponse.json();
    console.log("Workflow completed:", result);
    return result;
  }
}
```

--------------------------------

### Clone the with-assistant-ui example

Source: https://voltagent.dev/docs/ui/assistant-ui/

Clone the VoltAgent example project locally using npm create voltagent-app.

```bash
npm create voltagent-app@latest -- --example with-assistant-ui
```

--------------------------------

### Create VoltAgent project with Pinecone example

Source: https://voltagent.dev/docs/rag/pinecone/

Run this command to create a new VoltAgent project with the Pinecone example. It sets up a complete project with sample data and two agent configurations.

```bash
npm create voltagent-app@latest -- --example with-pinecone
cd with-pinecone
```

--------------------------------

### Get Workflow State - cURL Example

Source: https://voltagent.dev/docs/api/endpoints/workflows/

cURL command to retrieve the state of a workflow execution. Uses the endpoint GET /workflows/:id/executions/:executionId/state with a local server on port 3141.

```bash
curl http://localhost:3141/workflows/order-approval/executions/exec_123/state
```

--------------------------------

### Get Workflow State - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/workflows/

Example JSON response from the GET /workflows/:id/executions/:executionId/state endpoint. Shows the execution state including status, suspension details, input, and context.

```json
{
  "success": true,
  "data": {
    "executionId": "exec_1234567890_abc123",
    "workflowId": "order-approval",
    "status": "suspended",
    "replayedFromExecutionId": "exec_0987654321_replay",
    "replayFromStepId": "step-approval-1",
    "startAt": "2024-01-15T10:00:00.000Z",
    "suspension": {
      "suspendedAt": "2024-01-15T10:00:02.500Z",
      "reason": "Awaiting approval",
      "stepIndex": 2,
      "stepId": "approval-required"
    },
    "input": {
      "orderId": "ORD-123",
      "amount": 5000
    },
    "context": {
      "userId": "user-123",
      "priority": "high"
    }
  }
}
```

--------------------------------

### Build and Start with npm

Source: https://voltagent.dev/docs/quick-start/

Builds the app with npm and starts the compiled JavaScript with Node.

```bash
npm run build
npm start
```

--------------------------------

### Create project directory and initialize npm

Source: https://voltagent.dev/docs/manual-setup/

Run these commands to create a new project directory and initialize a package.json file.

```bash
mkdir my-voltagent-project
cd my-voltagent-project
npm init -y
```

--------------------------------

### Get Working Memory curl Command

Source: https://voltagent.dev/docs/api/endpoints/memory/

Example curl command for GET /api/memory/conversations/:conversationId/working-memory. Uses the scope query parameter set to 'conversation'. Note that scope=user requires userId in the query.

```bash
curl "http://localhost:3141/api/memory/conversations/conv-001/working-memory?scope=conversation"
```

--------------------------------

### Run with-copilotkit example

Source: https://voltagent.dev/docs/ui/copilotkit/

Use this command to create a new Voltagent app with the with-copilotkit example, which includes both server and Vite client.

```bash
npm create voltagent-app@latest -- --example with-copilotkit
```

--------------------------------

### List All Agents - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/agents/

Example response from GET /agents, showing a list of registered agents with their configurations.

```json
{
  "success": true,
  "data": [
    {
      "id": "assistant",
      "name": "Assistant",
      "description": "A helpful AI assistant",
      "status": "idle",
      "model": "gpt-4o-mini",
      "tools": [],
      "subAgents": [],
      "memory": null,
      "isTelemetryEnabled": false
    }
  ]
}
```

--------------------------------

### Install server and client dependencies

Source: https://voltagent.dev/docs/ui/assistant-ui/

Install VoltAgent server packages and Assistant UI client packages. The client packages are already included in the Assistant UI template.

```bash
# Server (VoltAgent)
pnpm add @voltagent/core @voltagent/libsql @voltagent/server-hono ai zod
pnpm add -D tsx

# Client (Assistant UI template already has these)
pnpm add @assistant-ui/react @assistant-ui/react-ai-sdk @assistant-ui/react-markdown
```

--------------------------------

### Run the development server and VoltAgent

Source: https://voltagent.dev/docs/ui/assistant-ui/

Run these commands to start the development server and the VoltAgent built-in server. Then open http://localhost:3000 to chat.

```bash
pnpm dev
pnpm voltagent:run
```

--------------------------------

### Connect via HTTP using MCPConfiguration

Source: https://voltagent.dev/docs/agents/mcp/mcp-server/

Client example that uses the MCP URL in MCPConfiguration to get tools over HTTP.

```ts
import { MCPConfiguration } from "@voltagent/core";

const mcpConfig = new MCPConfiguration({
  servers: {
    local: {
      type: "http",
      url: "http://localhost:3141/mcp/voltagent-example/mcp",
    },
  },
});

const tools = await mcpConfig.getTools();
```

--------------------------------

### Create Assistant UI project

Source: https://voltagent.dev/docs/ui/assistant-ui/

Run this command to scaffold a new Assistant UI project.

```bash
npx assistant-ui@latest create
```

--------------------------------

### Get Workflow Details - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/workflows/

Example JSON response from GET /workflows/:id, showing detailed workflow information including steps, schemas, and status. Note that schemas are converted from Zod to JSON Schema using zodSchemaToJsonUI.

```json
{
  "success": true,
  "data": {
    "id": "order-approval",
    "name": "Order Approval Workflow",
    "purpose": "Process and approve customer orders",
    "status": "idle",
    "stepsCount": 5,
    "steps": [
      {
        "id": "validate-order",
        "name": "Validate Order",
        "type": "andThen",
        "purpose": "Validate order data",
        "inputSchema": {
          /* JSON Schema */
        },
        "outputSchema": {
          /* JSON Schema */
        }
      },
      {
        "id": "check-inventory",
        "name": "Check Inventory",
        "type": "andThen",
        "purpose": "Verify stock availability"
      },
      {
        "id": "approval-required",
        "name": "Manager Approval",
        "type": "andWhen",
        "purpose": "Wait for manager approval if needed",
        "suspendSchema": {
          /* JSON Schema */
        },
        "resumeSchema": {
          /* JSON Schema */
        }
      }
    ],
    "inputSchema": {
      "type": "object",
      "properties": {
        "orderId": { "type": "string" },
        "amount": { "type": "number" },
        "items": { "type": "array" }
      },
      "required": ["orderId", "amount"]
    },
    "suspendSchema": null,
    "resumeSchema": null
  }
}
```

--------------------------------

### Start Chroma server

Source: https://voltagent.dev/docs/rag/chroma/

Starts the Chroma server at http://localhost:8000.

```bash
npm run chroma run
```

--------------------------------

### GET /api/memory/conversations/{conversationId}/messages

Source: https://voltagent.dev/docs/ui/ai-sdk-integration/

Fetches saved messages from memory for a specific conversation. The example shows how to retrieve messages after they have been persisted.

```APIDOC
## [GET] /api/memory/conversations/{conversationId}/messages

### Description
Fetches saved messages from memory for a specific conversation.

### Method
GET

### Endpoint
/api/memory/conversations/{conversationId}/messages

### Parameters
#### Path Parameters
- **conversationId** (string) - Required - The conversation thread ID.

#### Query Parameters
- **agentId** (string) - Required - The agent identifier.
- **userId** (string) - Required - The user identifier.

### Request Example
```bash
curl "http://localhost:3141/api/memory/conversations/conv-1/messages?agentId=assistant&userId=user-1"
```

### Response
#### Success Response (200)
No response schema documented.

#### Response Example
No response example documented.
```

--------------------------------

### Quick Start: createWorkflowChain with hooks

Source: https://voltagent.dev/docs/workflows/hooks/

Shows a complete workflow with onStart and onFinish hooks, including console output. Demonstrates how to define hooks in the createWorkflowChain configuration and run the workflow.

```typescript
import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

const workflow = createWorkflowChain({
  id: "order-processing",
  input: z.object({ orderId: z.string(), amount: z.number() }),
  hooks: {
    onStart: async (state) => {
      console.log(`Processing order ${state.data.orderId}`);
    },
    onFinish: async (info) => {
      if (info.status === "completed") {
        console.log(`Order ${info.state.data.orderId} completed!`);
      } else if (info.status === "error") {
        console.error(`Order failed: ${info.error}`);
      }
    },
  },
})
  .andThen({
    id: "validate-order",
    execute: async ({ data }) => ({ ...data, validated: true }),
  })
  .andThen({
    id: "charge-payment",
    execute: async ({ data }) => ({ ...data, charged: true }),
  });

await workflow.run({ orderId: "123", amount: 99.99 });
// Console output:
// Processing order 123
// Order 123 completed!
```

--------------------------------

### Expected startup output

Source: https://voltagent.dev/docs/rag/qdrant/

Shows the expected console output when the application starts, including agent descriptions, collection creation, and server startup details.

```text
🚀 VoltAgent with Qdrant is running!
📚 Two different agents are ready:
  1️⃣ Assistant with Retriever - Automatic semantic search on every interaction
  2️⃣ Assistant with Tools - LLM decides when to search autonomously

🔍 Try asking questions like:
  • 'What is VoltAgent?'
  • 'Tell me about vector databases'
  • 'How does Qdrant work?'
  • 'What is RAG?'

💡 The Tools Agent will automatically search when needed!

📋 Sources tracking: Both agents track which documents were used
   Check context.get('references') to see sources with IDs and scores
📋 Creating new collection "voltagent-knowledge-base"...


══════════════════════════════════════════════════
  VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
  ✓ HTTP Server:  http://localhost:3141
  ↪ Share it:    pnpm volt tunnel 3141 (secure HTTPS tunnel for teammates)
     Docs: https://voltagent.dev/deployment-docs/local-tunnel/
  ✓ Swagger UI:   http://localhost:3141/ui

  Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════
✅ Collection "voltagent-knowledge-base" created successfully
📚 Populating collection with sample documents...
✅ Successfully upserted 5 documents to collection
```

--------------------------------

### List Tools - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/tools/

Example response from GET /tools showing a tool named web_search with its schema and associated agents.

```json
{
  "success": true,
  "data": [
    {
      "name": "web_search",
      "description": "Search the web",
      "tags": ["search", "external-api"],
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "count": { "type": "number" }
        },
        "required": ["query"]
      },
      "status": "ready",
      "agents": [
        { "id": "assistant", "name": "Assistant" },
        { "id": "assistant-shadow", "name": "Assistant Shadow" }
      ]
    }
  ]
}
```

--------------------------------

### Run example locally with npm create voltagent-app

Source: https://voltagent.dev/docs/tools/reasoning-tool/

Command to scaffold and run the example locally using the with-thinking-tool template.

```bash
npm create voltagent-app@latest -- --example with-thinking-tool
```

--------------------------------

### createResumableChatHandlers generating POST and GET handlers

Source: https://voltagent.dev/docs/agents/resumable-streaming/

Generates POST and GET handlers for resumable chat. Requires agent and adapter. Optional waitUntil, logger, agentId, sendReasoning, sendSources, resolveInput, resolveConversationId, resolveUserId, resolveOptions. The example exports the generated handlers.

```TypeScript
import { createResumableChatHandlers } from "@voltagent/resumable-streams";

const { POST, GET } = createResumableChatHandlers({
  agent,
  adapter,
  resolveConversationId: ({ body }) => body.options.conversationId,
  resolveUserId: ({ body }) => body.options.userId,
});

export { POST, GET };
```

--------------------------------

### LanceDB Vector Database Setup

Source: https://voltagent.dev/docs/rag/overview/

Create a VoltAgent app with the with-lancedb example. LanceDB is a serverless vector database that runs locally or in the cloud.

```bash
npm create voltagent-app@latest -- --example with-lancedb
```

--------------------------------

### Set up MCP Docs Server with volt mcp setup

Source: https://voltagent.dev/docs/ai-assistants/

Run this command in existing projects to configure the MCP Docs Server. It is an alternative to manual IDE configuration.

```bash
volt mcp setup
```

--------------------------------

### POST /setup-observability

Source: https://voltagent.dev/docs/api/api-reference/

Configure VoltAgent keys for observability. No authentication required.

```APIDOC
## POST /setup-observability

### Description
Configure VoltAgent keys for observability.

### Method
POST

### Endpoint
/setup-observability

### Request Body
- **keys** (object) - Required - VoltAgent keys to configure.

### Request Example
{
  "keys": {}
}

### Response
#### Success Response (200)
- **status** (string) - Configuration status.

#### Response Example
{
  "status": "configured"
}
```

--------------------------------

### Before (Deprecated): Using @voltagent/anthropic-ai

Source: https://voltagent.dev/docs/getting-started/providers-models/

Shows the deprecated way of using VoltAgent's native Anthropic provider. This is the 'Before' example in the migration guide.

```typescript
import { AnthropicProvider } from "@voltagent/anthropic-ai";

const provider = new AnthropicProvider({ apiKey: "..." });
const agent = new Agent({
  llm: provider,
  model: "claude-opus-4-1",
});
```

--------------------------------

### Quick Start: andTap in a Workflow

Source: https://voltagent.dev/docs/workflows/steps/and-tap/

A complete workflow example showing andTap used between andThen steps to log the total without modifying the data.

```typescript
import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

const workflow = createWorkflowChain({
  id: "process-order",
  input: z.object({ orderId: z.string() }),
})
  .andThen({
    id: "calculate-total",
    execute: async ({ data }) => ({
      ...data,
      total: 100,
    }),
  })
  .andTap({
    id: "log-total",
    execute: ({ data }) => {
      console.log(`Order ${data.orderId} total: $${data.total}`);
    },
  })
  .andThen({
    id: "charge-customer",
    execute: async ({ data }) => ({
      ...data,
      charged: true,
    }),
  });

// Console: "Order 123 total: $100"
// Result: { orderId: "123", total: 100, charged: true }
```

--------------------------------

### Create example project and run smoke test

Source: https://voltagent.dev/docs/agents/a2a/a2a-server/

Run these commands to create the example project with the A2A server and execute its smoke test. The test verifies message sending, streaming, and cancellation propagation.

```bash
npm create voltagent-app@latest -- --example with-a2a-server
cd with-a2a-server
pnpm test:smoke
```

--------------------------------

### Resume Workflow Response

Source: https://voltagent.dev/docs/api/endpoints/workflows/

Example response from the resume endpoint, showing the execution ID, start and end times, status 'completed', and result data.

```json
{
  "success": true,
  "data": {
    "executionId": "exec_1234567890_abc123",
    "startAt": "2024-01-15T10:00:00.000Z",
    "endAt": "2024-01-15T10:35:20.456Z",
    "status": "completed",
    "result": {
      "approved": true,
      "finalAmount": 4500,
      "processedSteps": 5
    }
  }
}
```

--------------------------------

### Search Memory curl Command

Source: https://voltagent.dev/docs/api/endpoints/memory/

Example curl command for GET /api/memory/search. Requires embedding and vector adapters; otherwise the endpoint returns 400.

```bash
curl "http://localhost:3141/api/memory/search?searchQuery=refund%20policy&limit=5"
```

--------------------------------

### List Workflow Executions - JSON Response

Source: https://voltagent.dev/docs/api/endpoints/workflows/

Example response from the GET /workflows/executions endpoint. Shows a completed workflow execution with input, metadata, events, and output.

```json
{
  "success": true,
  "data": [
    {
      "id": "6a8ca92c-0d8a-425f-b24f-09f841a8c200",
      "workflowId": "order-approval",
      "workflowName": "Order Approval Workflow",
      "status": "completed",
      "userId": "user-123",
      "input": {
        "employeeId": "sample-employeeId",
        "amount": 42,
        "category": "sample-category",
        "description": "sample-description"
      },
      "metadata": {
        "traceId": "abe55638e17097f497bfb7ba5ed92a50",
        "spanId": "0704efe9b0bf5bfc"
      },
      "events": [
        {
          "id": "3a290355-4baa-4e48-9502-f8d314fb008e",
          "type": "workflow-start",
          "name": "Expense Approval Workflow",
          "from": "Expense Approval Workflow",
          "startTime": "2025-12-10T15:18:04.423Z",
          "endTime": "2025-12-10T15:18:04.423Z",
          "status": "running",
          "input": {
            "employeeId": "sample-employeeId",
            "amount": 42,
            "category": "sample-category",
            "description": "sample-description"
          }
        },
        {
          "id": "8d80ee68-bd2d-451f-abed-856845280509",
          "type": "workflow-complete",
          "name": "Expense Approval Workflow",
          "from": "Expense Approval Workflow",
          "startTime": "2025-12-10T15:18:05.415Z",
          "endTime": "2025-12-10T15:18:05.415Z",
          "status": "success",
          "output": {
            "status": "approved",
            "approvedBy": "system",
            "finalAmount": 42
          }
        }
      ],
      "output": {
        "status": "approved",
        "approvedBy": "system",
        "finalAmount": 42
      },
      "createdAt": "2025-12-10T15:18:04.421Z",
      "updatedAt": "2025-12-10T15:18:05.413Z"
    }
  ]
}
```

--------------------------------

### Start REST API Stream via SSE

Source: https://voltagent.dev/docs/workflows/streaming/

Use this TypeScript example to start a workflow stream via the REST API endpoint /workflows/expense-approval/stream. It sends a POST request with input and options, then processes the SSE response. Note that the stream closes on suspension due to stateless architecture.

```typescript
// Start workflow stream via REST API
const response = await fetch("http://localhost:3141/workflows/expense-approval/stream", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    input: {
      employeeId: "EMP001",
      amount: 750,
      category: "travel",
      description: "Conference attendance",
    },
    options: {
      userId: "user-123",
      executionId: "exec-456",
    },
  }),
});

// Process SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  // Parse SSE events (lines starting with "data: ")
  const lines = text.split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      console.log(`[${event.type}] ${event.from}`, event);

      if (event.type === "workflow-suspended") {
        console.log("Workflow suspended - stream will close");
        // Stream closes here - stateless architecture
      }
    }
  }
}
```

--------------------------------

### Install OpenTelemetry packages

Source: https://voltagent.dev/docs/observability/mlflow/

Install the OpenTelemetry SDK and OTLP protobuf exporter using npm.

```bash
npm install @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto
```

--------------------------------

### Clone starter projects with npm create voltagent-app

Source: https://voltagent.dev/docs/ui/overview/

Use these commands to clone example UIs for Assistant UI, Next.js, and CopilotKit. Each command creates a new project with the specified example.

```bash
npm create voltagent-app@latest -- --example with-assistant-ui
npm create voltagent-app@latest -- --example with-nextjs
npm create voltagent-app@latest -- --example with-copilotkit
```

--------------------------------

### Connect via stdio using MCPClient

Source: https://voltagent.dev/docs/agents/mcp/mcp-server/

Client example that spawns a local process and communicates over stdin/stdout. Replace command/args with the entry that starts your VoltAgent + MCP server.

```ts
import { MCPClient } from "@voltagent/core";

const client = new MCPClient({
  clientInfo: { name: "local-client", version: "0.1.0" },
  server: {
    type: "stdio",
    command: "node",
    args: ["dist/index.js"],
    cwd: process.cwd(),
    env: { ...process.env },
  },
});

await client.connect();
const tools = await client.listTools();
```

--------------------------------

### Install @voltagent/postgres with npm

Source: https://voltagent.dev/docs/agents/memory/postgres/

Install the PostgreSQL adapter package using npm.

```bash
npm install @voltagent/postgres
```

--------------------------------

### Test agent with InMemoryStorageAdapter

Source: https://voltagent.dev/docs/agents/memory/in-memory/

Creates an Agent with an InMemoryStorageAdapter for testing without database setup. The example shows how to pass memory configuration with userId and conversationId when generating text.

```TypeScript
import { Agent, Memory, InMemoryStorageAdapter } from "@voltagent/core";

const testAgent = new Agent({
  name: "Test Assistant",
  model: "openai/gpt-4o-mini",
  memory: new Memory({
    storage: new InMemoryStorageAdapter(),
  }),
});

// Test conversations without persistence
await testAgent.generateText("Test message", {
  memory: {
    userId: "test-user",
    conversationId: "test-conversation",
  },
});
```

--------------------------------

### Install required packages

Source: https://voltagent.dev/docs/getting-started/migration-guide/

Commands to install the new modular packages (@voltagent/core, @voltagent/server-hono, @voltagent/libsql, @voltagent/logger) and the base ai library using npm, yarn, or pnpm.

```bash
npm install @voltagent/core@latest @voltagent/server-hono@latest @voltagent/libsql@latest @voltagent/logger@latest ai
# yarn add @voltagent/core@latest @voltagent/server-hono@latest @voltagent/libsql@latest @voltagent/logger@latest ai@latest
# pnpm add @voltagent/core@latest @voltagent/server-hono@latest @voltagent/libsql@latest @voltagent/logger@latest ai@latest
```

--------------------------------

### After (Recommended): Using Vercel AI SDK provider

Source: https://voltagent.dev/docs/getting-started/providers-models/

Shows the recommended way of using Vercel AI SDK providers with VoltAgent. This is the 'After' example in the migration guide.

```typescript
import { Agent } from "@voltagent/core";

const agent = new Agent({
  model: "anthropic/claude-3-5-sonnet",
  instructions: "You are a helpful assistant",
});
```
Tokens:
Raw