前言¶
用 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 共用的默认MemoryagentMemory：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。编写新配置时应避免继续依赖这些字段。
生命周期要点¶
官方生命周期说明摘要如下：
- 构造时注册 agents 与 workflows。
- 若提供了 server 提供方，会自动启动 server。
- 为 agents 与 workflows 应用默认 memory 配置。
- 若未显式提供
voltOpsClient，会尝试用环境变量VOLTAGENT_PUBLIC_KEY与VOLTAGENT_SECRET_KEY自动配置 VoltOps 客户端。 - 初始化 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。
