必须先执行veadk init my-agent --template=chat创建标准项目结构，再定义带@tool装饰器的工具函数并注册到agent类，配置knowledge块接入qdrant，通过agentkit serve验证流式响应，最后用agentkit build打包并上传至火山引擎部署。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
初始化 veADK 项目结构
使用 veADK 搭建智能体前，必须先创建符合 AgentKit 规范的本地项目骨架，否则后续工具调用、记忆注入和云端发布将全部失败。
在终端中执行：veadk init my-agent --template=chat。该命令会生成含 agent.py、tools/、memory/ 和 config.yaml 的标准目录结构。
注意：模板名必须为 chat、task 或 retrieval 三者之一，其他值会导致 【config.yaml 中的 runtime.type 字段无法被 agentkit build 识别】，构建时直接报错退出。
定义核心 Agent 类并注册工具
打开 agent.py，替换默认内容为以下代码：
from veadk import Agent, tool<br>from typing import Dict, Any<br><br>@tool<br>def search_knowledge(query: str) -> Dict[str, Any]:<br> return {"result": f"Mock answer for '{query}'"}<br><br>class MyAgent(Agent):<br> def run(self, input: str) -> str:<br> res = search_knowledge(input)<br> return f"Got: {res['result']}"
这段代码声明了一个可被 AgentKit 调度的工具函数，并将其集成进 MyAgent 的主逻辑中。工具函数必须用 @tool 装饰器标记，否则 【agentkit serve 本地调试时不会加载该函数，调用返回空响应】。
保存后，在项目根目录运行 veadk check 验证语法与组件注册是否正确。若输出 “✓ All checks passed”，说明工具已成功绑定。
配置知识库接入与 RAG 流程
AgentKit 支持通过 knowledge 配置块自动挂载向量库。编辑 config.yaml，在末尾添加：
knowledge:<br> type: "qdrant"<br> host: "localhost"<br> port: 6333<br> 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 \<br> -H "Content-Type: application/json" \<br> -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），否则会出现 【模型权重加载失败：mismatched tokenizer config version】 错误。
第四步：点击「部署」，等待状态变为「运行中」。此时可通过控制台提供的公网 endpoint 直接发起生产调用。
