火山引擎AgentKit搭建智能体完整操作步骤(代码示例)

必须先执行veadk init my-agent --template=chat创建标准项目结构，再定义带@tool装饰器的工具函数并注册到Agent类，配置knowledge块接入Qdrant，通过agentkit serve验证流式响应，最后用agentkit build打包并上传至火山引擎部署。

初始化 veADK 项目结构

使用 veADK 搭建智能体前，必须先创建符合 AgentKit 规范的本地项目骨架，否则后续工具调用、记忆注入和云端发布将全部失败。

在终端中执行：veadk init my-agent --template=chat。该命令会生成含 agent.py、tools/、memory/ 和 config.yaml 的标准目录结构。

注意：模板名必须为 chat、task 或 retrieval 三者之一，其他值会导致

，构建时直接报错退出。

定义核心 Agent 类并注册工具

打开 agent.py，替换默认内容为以下代码：

from veadk import Agent, tool  # 从veadk模块导入Agent和tool
from typing import Dict, Any  # 从typing模块导入Dict和Any

@tool  # 使用tool装饰器
def search_knowledge(query: str) -> Dict[str, Any]:  # 定义search_knowledge函数，接受一个字符串query作为参数，返回一个字典类型的数据
    return {"result": f"Mock answer for '{query}'"}  # 返回一个包含'result'键的字典，其值为一个格式化字符串，表示对query的模拟回答

class MyAgent(Agent):  # 定义MyAgent类，继承自Agent类
    def run(self, input: str) -> str:  # 定义run方法，接受一个字符串input作为参数，返回一个字符串类型的数据
        res = search_knowledge(input)  # 调用search_knowledge函数，传入input参数，将返回结果赋值给res变量
        return f"Got: {res['result']}"  # 返回一个格式化字符串，表示获取到的结果

这段代码声明了一个可被 AgentKit 调度的工具函数，并将其集成进 MyAgent 的主逻辑中。工具函数必须用 @tool 装饰器标记，否则

。

保存后，在项目根目录运行 veadk check 验证语法与组件注册是否正确。若输出 “✓ All checks passed”，说明工具已成功绑定。

配置知识库接入与 RAG 流程

AgentKit 支持通过 knowledge 配置块自动挂载向量库。编辑 config.yaml，在末尾添加：

knowledge:
  type: "qdrant"
  host: "localhost"
  port: 6333
  collection: "my_docs"

这一步不启动 Qdrant 服务也能通过 veadk check，但实际运行 agentkit serve 时会立即连接并尝试拉取 schema。若端口不通或 collection 不存在，服务将在启动后 3 秒内崩溃并打印 “Failed to initialize knowledge client”。

需先用Docker启动Qdrant，命令为：docker run -d -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant。启动完成后，再执行 curl -X PUT "http://localhost:6333/collections/my_docs" -H 'Content-Type: application/json' --data-raw '{"vector_size": 1024, "distance": "Cosine"}' 来创建集合。

本地调试与流式响应验证

执行 agentkit serve --port 8000 启动调试服务。服务启动成功后，终端会显示 “Agent server running on http://localhost:8000”。

新开终端，发送流式请求测试：

curl -N http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "解释量子纠缠", "stream": true}'

若看到逐字返回的 data: {"delta":"Q"}、data: {"delta":"u"} 等事件行，说明 AgentKit 的实时事件流机制已就绪。此模式下前端可直接用 EventSource 接收，无需额外 WebSocket 封装。

若返回完整 JSON 响应而非 SSE 格式，检查请求体中 "stream": true 是否拼写正确——少一个引号或写成 Stream: true 都会导致降级为同步响应。

打包并发布至火山引擎云环境

第一步：执行 agentkit build。该命令读取 config.yaml 中的 runtime.type 和 entrypoint，生成 dist/my-agent-v0.1.0.tar.gz。

第二步：登录火山引擎控制台 → 进入 Agent Plan 页面 → 点击「新建智能体」→ 选择「从本地上传」→ 上传刚生成的 tar 包。

第三步：在部署配置页，确认「运行时版本」与本地 veadk --version 输出一致（当前最新稳定版为 0.8.3），否则会出现

错误。

第四步：点击「部署」，等待状态变为「运行中」。此时可通过控制台提供的公网 endpoint 直接发起生产调用。