Back to Details

voltagent-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VoltAgent Best Practices

VoltAgent 最佳实践

Quick reference for VoltAgent conventions and patterns.
VoltAgent 规范与模式速查手册。

Choosing Agent or Workflow

选择 Agent 还是 Workflow

UseWhen
AgentOpen-ended tasks that require tool selection and adaptive reasoning
WorkflowMulti-step pipelines with explicit control flow and suspend/resume
使用场景适用时机
Agent需要工具选择和自适应推理的开放式任务
Workflow具有显式控制流和暂停/恢复功能的多步骤流水线

Layout

项目布局

src/
|-- index.ts
|-- agents/
|-- tools/
`-- workflows/
src/
|-- index.ts
|-- agents/
|-- tools/
`-- workflows/

Quick Snippets

快速代码片段

Basic Agent

基础 Agent

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

const agent = new Agent({
  name: "assistant",
  instructions: "You are helpful.",
  model: "openai/gpt-4o-mini",
});
Model format is 
provider/model
(for example 
openai/gpt-4o-mini
or 
anthropic/claude-3-5-sonnet
).
typescript
import { Agent } from "@voltagent/core";

const agent = new Agent({
  name: "assistant",
  instructions: "You are helpful.",
  model: "openai/gpt-4o-mini",
});
模型格式为
provider/model
（例如
openai/gpt-4o-mini
或
anthropic/claude-3-5-sonnet
）。

Basic Workflow

基础 Workflow

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

const workflow = createWorkflowChain({
  id: "example",
  input: z.object({ text: z.string() }),
  result: z.object({ summary: z.string() }),
}).andThen({
  id: "summarize",
  execute: async ({ data }) => ({ summary: data.text }),
});
typescript
import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";

const workflow = createWorkflowChain({
  id: "example",
  input: z.object({ text: z.string() }),
  result: z.object({ summary: z.string() }),
}).andThen({
  id: "summarize",
  execute: async ({ data }) => ({ summary: data.text }),
});

VoltAgent Bootstrap

VoltAgent 启动代码

typescript
import { VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";

new VoltAgent({
  agents: { agent },
  workflows: { workflow },
  server: honoServer(),
});
typescript
import { VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";

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

Memory Defaults

内存默认配置

  • Use 
    memory
    for a shared default across agents and workflows.
  • Use 
    agentMemory
    or 
    workflowMemory
    when defaults need to differ.
  • 使用
    memory
    在Agent和工作流之间共享默认配置。
  • 当默认配置需要区分时，使用
    agentMemory
    或
    workflowMemory
    。

Server Options

服务器选项

  • Use 
    @voltagent/server-hono
    for Node HTTP servers.
  • Use 
    @voltagent/server-elysia
    as an alternative Node server provider.
  • Use 
    serverless
    provider for fetch runtimes (Cloudflare, Netlify).
  • 使用
    @voltagent/server-hono
    搭建Node HTTP服务器。
  • 可选择
    @voltagent/server-elysia
    作为替代的Node服务器提供商。
  • 对于Fetch运行时（Cloudflare、Netlify），使用
    serverless
    提供商。

Observability Notes

可观测性说明

  • Use 
    VoltOpsClient
    or 
    createVoltAgentObservability
    for tracing.
  • VoltAgent will auto-configure VoltOps if 
    VOLTAGENT_PUBLIC_KEY
    and 
    VOLTAGENT_SECRET_KEY
    are set.
  • 使用
    VoltOpsClient
    或
    createVoltAgentObservability
    进行追踪。
  • 如果设置了
    VOLTAGENT_PUBLIC_KEY
    和
    VOLTAGENT_SECRET_KEY
    ，VoltAgent将自动配置VoltOps。

Recipes

实践示例

Short best-practice recipes live in the embedded docs:
  • packages/core/docs/recipes/
  • Search: 
    rg -n "keyword" packages/core/docs/recipes -g"*.md"
  • Read: 
    cat packages/core/docs/recipes/<file>.md
简短的最佳实践示例位于嵌入式文档中：
  • packages/core/docs/recipes/
  • 搜索：
    rg -n "keyword" packages/core/docs/recipes -g"*.md"
  • 阅读：
    cat packages/core/docs/recipes/<file>.md

Footguns

注意事项

  • Do not use 
    JSON.stringify
    inside VoltAgent packages. Use 
    safeStringify
    from 
    @voltagent/internal
    .
  • 不要在VoltAgent包内使用
    JSON.stringify
    ，请使用
    @voltagent/internal
    中的
    safeStringify
    。

Resources

资源