voltagent-best-practices

VoltAgent 最佳实践

VoltAgent 约定和模式速查。

---

选择 Agent 或工作流

用途	适用场景
Agent	需要选择工具并进行自适应推理的开放式任务
工作流	控制流明确且支持暂停／恢复的多步骤管道

---

目录结构

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

---

快速代码片段

基本 Agent

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）。

基本工作流

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 引导程序

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

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

---

内存默认设置

• 使用 memory，为所有 Agent 和工作流设置共享默认值。
• 如果需要使用不同的默认值，请使用 agentMemory 或 workflowMemory。

---

服务端选项

• Node HTTP 服务使用 @voltagent/server-hono。
• 也可使用 @voltagent/server-elysia 作为 Node 服务提供方。
• fetch 运行时（Cloudflare、Netlify）使用 serverless 提供方。

---

可观测性说明

• 使用 VoltOpsClient 或 createVoltAgentObservability 进行追踪。
• 如果设置了 VOLTAGENT_PUBLIC_KEY 和 VOLTAGENT_SECRET_KEY，VoltAgent 将自动配置 VoltOps。

---

配方

嵌入式文档中提供了简短的最佳实践配方：

• packages/core/docs/recipes/
• 搜索：rg -n "keyword" packages/core/docs/recipes -g"*.md"
• 阅读：cat packages/core/docs/recipes/<file>.md

---

易踩的坑

• 不要在 VoltAgent 包中使用 JSON.stringify。请使用 @voltagent/internal 中的 safeStringify。

---

资源

• https://voltagent.dev/docs
• https://github.com/voltagent/voltagent
• https://github.com/voltagent/voltagent/tree/main/examples