前言¶

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