前言¶

用 VoltAgent 搭 TypeScript Agent 应用时，VoltAgent 构造选项、生命周期顺序和公开方法往往要对照 @voltagent/core 源码或零散文档。字段是否已废弃、MCP/A2A 何时初始化、server 与 serverless 如何接入，容易在实现阶段反复查仓库。下面介绍 voltagent-core-reference：把 VoltAgent 类相关说明整理成 Agent Skill，供编码助手在对话中按需引用，减少猜配置和漏掉初始化步骤的情况。

这是什么¶

voltagent-core-reference 是面向 @voltagent/core 中 VoltAgent 类的参考型 Skill。官方说明其覆盖构造选项、生命周期行为、方法签名，以及 server / serverless 的常见接入方式。资料中标注来源文件为 packages/core/src/voltagent.ts 与 packages/core/src/types.ts。

Skill 由 VoltAgent 团队维护，仓库为 VoltAgent/skills，本 Skill 目录为 skills/voltagent-core-reference。许可证为 MIT，Skill 元数据版本为 1.0.0。在 officialskills.sh 上归类为官方 AI 工具类 Skill，并强调「嵌入文档」思路：不替代框架文档站，而是在助手上下文中直接呈现选项名、方法与生命周期要点。

核心功能¶

Skill 正文（SKILL.md）主要包含以下几块，均来自官方仓库内容。

构造选项（VoltAgentOptions）¶

VoltAgentOptions 支持的主要字段包括：

• agents：Agent 实例注册表
• workflows：Workflow 或 WorkflowChain 实例注册表
• memory：Agent 与 Workflow 共用的默认 Memory
• agentMemory：Agent 专用默认 Memory（未设置时回退到 memory）
• workflowMemory：Workflow 专用默认 Memory（未设置时回退到 memory）
• toolRouting：全局 ToolRoutingConfig 默认项
• triggers：VoltAgentTriggersConfig 处理器
• server：服务端提供方工厂（示例：honoServer()）
• serverless：面向 fetch 运行时的 serverless 提供方工厂
• voltOpsClient：共享的 VoltOpsClient 实例
• observability：VoltAgentObservability 实例
• logger：共享 Logger 实例
• mcpServers：MCP 服务或工厂注册表
• a2aServers：A2A 服务或工厂注册表
• checkDependencies：设为 false 可跳过依赖检查

已标记为废弃的选项包括：port、autoStart、customEndpoints、enableSwaggerUI。编写新配置时应避免继续依赖这些字段。

生命周期要点¶

官方生命周期说明摘要如下：

1. 构造时注册 agents 与 workflows。
2. 若提供了 server 提供方，会自动启动 server。
3. 为 agents 与 workflows 应用默认 memory 配置。
4. 若未显式提供 voltOpsClient，会尝试用环境变量 VOLTAGENT_PUBLIC_KEY 与 VOLTAGENT_SECRET_KEY 自动配置 VoltOps 客户端。
5. 初始化 MCP 与 A2A server，并在 server 启动后启动 MCP transport。

公开方法¶

Skill 列出的常用方法包括：

• 注册：registerAgent(agent)、registerAgents(agents)、registerWorkflow(workflow)、registerWorkflows(workflows)、registerTrigger(name, config)、registerTriggers(triggers)
• 查询：getAgent(id)、getAgents()、getAgentCount()、getWorkflow(id)、getWorkflows()、getWorkflowCount()、getObservability()
• 服务：startServer()、stopServer()、getServerInstance()、serverless()（访问 serverless 提供方）
• 收尾：shutdown()（优雅关闭）、shutdownTelemetry()（观测相关关闭）

安装与启用¶

官方skills 站点给出的安装方式为：

npx skills add https://github.com/VoltAgent/skills --skill voltagent-core-reference

也可将 Skill 目录链接交给支持 Skills 的编码助手，由其按环境约定安装：https://github.com/VoltAgent/skills/tree/main/skills/voltagent-core-reference。

本任务资料未区分 Cursor、Codex CLI、Claude Code 的安装差异；以你当前工具对 npx skills add 或等价「添加 Skill」流程的支持为准。

典型用法¶

Skill 内附的最小示例展示如何用 Hono server 提供方创建实例并启动服务：

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

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

await app.startServer();

上面代码说明：在构造时传入 agents、workflows 与 server 工厂；需要显式调用 startServer() 时按项目启动流程执行。若走 serverless 路径，资料指向通过实例的 serverless() 访问对应提供方，具体部署需结合 @voltagent/core 与你选用的 serverless 适配包文档。

适用场景与注意¶

适合在以下情况启用该 Skill：

• 在 VoltAgent 实例上注册 MCP、A2A server，需要确认注册表字段与启动顺序。
• 为 Agent 与 Workflow 分别配置 memory 提供方（agentMemory / workflowMemory）。
• 使用 serverless() 对接 fetch 运行时部署。
• 运行时用 getAgent()、registerAgents() 等动态注册或查询 Agent。
• 通过 voltOpsClient 或环境变量密钥连接 VoltOps，统一运行时观测。

使用时的限制：

• 这是参考型 Skill，不替代完整教程或 API 变更公告；框架大版本升级后应以仓库内 SKILL.md 与 voltagent.ts 为准再核对。
• 废弃选项仍可能在旧示例中出现，启用 Skill 有助于助手提醒勿再使用 port、autoStart 等字段。
• Skill 不保证覆盖 @voltagent/core 全部类型细节，复杂自定义类型仍需查源码或官方文档。

结尾¶

voltagent-core-reference 把 VoltAgent 核心类的选项、生命周期与方法收敛进 Skill，适合在 TypeScript Agent 项目里与助手协作时减少翻源码成本。官方地址：https://github.com/voltagent/skills/tree/main/skills/voltagent-core-reference。