AgentKit CLI快速入门：Basic Agent模板从开发到部署实战

安全阿岳

2026-8-31

[1] 一句话结论

AgentKit CLI用Basic Agent模板从init到deploy只需5步，30分钟跑通第一个Agent，本地调试+云端部署全流程。

[2] 适用场景与不适用场景

适用场景

你已经安装了AgentKit CLI（参考安装教程），现在想从零开始开发第一个Agent应用。你不想看冗长的概念文档，希望有一份手把手的实战教程，从创建项目、编写配置、本地调试、测试到部署上线，一步步跟着做就能跑通。
这篇文章用Basic Agent模板（最简单的Agent类型），带你完整走一遍从开发到部署的全流程。每一步都有具体的命令、代码和预期结果，跟着做就能在30分钟内拥有自己的第一个Agent。
适合：刚安装AgentKit CLI想快速上手的开发者、想了解Agent开发全流程的技术人员、需要团队培训材料的技术负责人。

不适用场景

还没安装AgentKit CLI：先完成安装，参考安装教程。
想开发复杂Agent（多工具、工作流、知识库）：Basic Agent是入门模板，复杂Agent参考进阶教程。
只想使用现成Agent不开发：直接用ArkClaw CLI，不需要开发。

[3] 前置准备

AgentKit CLI已安装（agentkit --version确认）
Python 3.10+环境
火山引擎方舟API Key（有可用的推理接入点）
基本的命令行和Python基础
预计耗时：30分钟（含调试和部署）

[4] 分步实现

步骤1：创建Basic Agent项目

打开终端，执行：
agentkit init my-first-agent --template basic
cd my-first-agent
--template basic指定使用Basic Agent模板（最简单的对话Agent，不含工具和知识库）。
生成的项目结构：

my-first-agent/
├── agent.yaml              # Agent核心配置
├── system-prompt.md        # 系统提示词
├── tests/
│   └── test_agent.py       # 测试用例
├── environments/
│   ├── dev.yaml            # 开发环境配置
│   └── prod.yaml           # 生产环境配置
├── requirements.txt        # Python依赖
├── .gitignore
└── README.md

查看默认配置：
cat agent.yaml
默认内容：

name: my-first-agent
description: 我的第一个Agent
model:
  provider: volcengine
  model_id: REPLACE_WITH_YOUR_ENDPOINT_ID
  temperature: 0.7
  max_tokens: 2048
environment: dev

步骤2：配置模型和API Key

编辑agent.yaml，替换模型ID：
将model_id字段的REPLACE_WITH_YOUR_ENDPOINT_ID替换为你在火山方舟控制台创建的推理接入点ID（如ep-20240827xxxxxx）。
也可以用命令快速编辑：
sed -i 's/REPLACE_WITH_YOUR_ENDPOINT_ID/你的接入点ID/' agent.yaml
配置API Key（环境变量方式，推荐）：
export VOLCENGINE_API_KEY="你的API Key"
为了持久化，添加到~/.zshrc或~/.bashrc：
echo 'export VOLCENGINE_API_KEY="你的API Key"' >> ~/.zshrc
source ~/.zshrc
验证配置：
agentkit config validate
输出"Configuration is valid"表示配置正确。如果报错，根据提示修正。

⚠️ 常见错误：配置验证失败"model_id is required"
原因：agent.yaml中的model_id没有替换，还是默认的占位符。
解决：1）编辑agent.yaml，将model_id改为真实的推理接入点ID；2）确认接入点在方舟控制台状态为"运行中"；3）重新执行agentkit config validate验证。

步骤3：编写系统提示词

系统提示词定义Agent的角色、行为和能力，是Agent的"灵魂"。
编辑system-prompt.md：

你是一个友好的编程助手，名叫"小助手"。

你的能力：
1. 用简洁清晰的语言回答编程问题
2. 提供可直接运行的代码示例，代码必须有注释
3. 主动指出代码中的潜在问题和改进建议
4. 遇到不确定的问题，诚实说明"我不确定"，不要编造答案

你的风格：
- 专业但不生硬，像一个靠谱的同事
- 回答先给结论，再给细节
- 代码用Markdown代码块包裹，注明语言

限制：
- 只回答编程相关问题，非编程问题礼貌拒绝
- 不提供违法、有害的代码

保存后，Agent在对话时会遵循这些规则。

技巧：系统提示词是Agent效果的关键。花时间打磨提示词，比换模型更能提升效果。建议：1）明确角色和能力边界；2）给出输出格式要求；3）加入示例（few-shot）；4）说明限制和禁止行为。

步骤4：本地调试

启动本地调试服务：
agentkit dev
输出：

AgentKit Dev Server
Agent: my-first-agent
Environment: dev
URL: http://localhost:8080
Model: doubao-pro-32k
Press Ctrl+C to stop

在浏览器中测试：
打开http://localhost:8080，看到对话界面。
测试1：输入"你好，你是谁？"
预期：Agent回复"你好！我是小助手，一个编程助手..."（包含系统提示词中定义的角色名）
测试2：输入"用Python写一个快速排序"
预期：Agent返回带注释的Python快速排序代码
测试3：输入"今天天气怎么样？"（非编程问题）
预期：Agent礼貌拒绝，说明只回答编程问题
查看调试信息：
调试界面右侧显示：

每次对话的输入/输出token数
模型调用耗时
系统提示词预览
工具调用日志（Basic Agent无工具，显示为空）
热重载测试：
修改system-prompt.md（如把角色名改为"代码小助手"），保存后回到对话界面，不需要重启，输入"你是谁？"确认角色名已更新。

技巧：agentkit dev是开发阶段最常用的命令。建议一直开着，边改边测。调试界面的token统计帮助你控制成本——如果每次对话token很高，考虑精简系统提示词。

步骤5：编写测试用例

在部署前，先写自动化测试确保Agent行为符合预期。
编辑tests/test_agent.py：

def test_agent_introduces_itself(agent):
    '''测试Agent能正确介绍自己'''
    response = agent.chat("你是谁？")
    assert "小助手" in response or "编程助手" in response
def test_agent_provides_code(agent):
    '''测试Agent能提供代码示例'''
    response = agent.chat("用Python写一个hello world")
    assert "python" in response.lower() or "print" in response
def test_agent_rejects_non_programming(agent):
    '''测试Agent拒绝非编程问题'''
    response = agent.chat("今天股票怎么样？")
    assert "编程" in response or "抱歉" in response or "无法" in response

运行测试：
agentkit test
输出：

Running 3 tests...
✓ test_agent_introduces_itself (2.3s)
✓ test_agent_provides_code (1.8s)
✓ test_agent_rejects_non_programming (1.5s)
All 3 tests passed!

如果测试失败，根据失败信息调整系统提示词或测试用例。

注意：测试会消耗token（每次测试调用一次模型）。大量测试时注意成本。可以用mock模式（agentkit test --mock）不调用真实模型，只验证配置和流程。

步骤6：打包和部署到云端

测试通过后，打包并部署到火山引擎方舟平台。
打包：
agentkit build --env prod
输出：

Building agent...
Environment: prod
Output: dist/my-first-agent-1.0.0.agent
Build successful!

打包产物在dist/目录下，包含配置、提示词、依赖声明。
部署：
agentkit deploy --env prod
输出：

Deploying to 火山引擎方舟...
Agent: my-first-agent
Version: 1.0.0
Deploying... ✓
Deployment successful!
Agent ID: agent-xxxxxxxx
Endpoint URL: https://ark.cn-beijing.volces.com/agent/xxxxxxxx
Status: running

验证部署：
agentkit status
输出Agent状态、版本、端点URL、调用量。
用curl测试部署的Agent：
curl -X POST https://ark.cn-beijing.volces.com/agent/xxxxxxxx -H "Authorization: Bearer 你的API Key" -H "Content-Type: application/json" -d '{"prompt": "你好"}'
确认返回Agent回复。
查看生产日志：
agentkit logs --env prod --tail 50
查看最近50条生产日志，排查问题。

部署注意：1）首次部署可能需要1-2分钟（创建资源、加载模型）；2）部署后Agent状态从deploying变为running；3）生产环境的API Key在environments/prod.yaml中配置，和dev环境隔离；4）部署后可以在方舟控制台查看Agent详情和监控。

[5] 实际验证

按本文6步完成后，执行最终验证：测试1 本地agentkit dev启动，浏览器对话正常，角色名和系统提示词一致；测试2 agentkit test全部测试通过；测试3 agentkit build打包成功，dist目录有产物；测试4 agentkit deploy部署成功，状态为running；测试5 curl调用部署端点返回正常回复。成功标志：5项全部通过，第一个Agent从开发到部署全流程跑通。

[6] 常见问题 FAQ

Q1：部署后Agent回复和本地调试不一样，为什么？
A：常见原因：1）环境配置不同：dev和prod环境的model_id、temperature、max_tokens可能不同，检查environments/prod.yaml；2）系统提示词未更新：部署时打包的是构建时的文件，如果build后修改了system-prompt.md，需要重新build+deploy；3）模型版本差异：dev和prod用了不同的模型或接入点，行为可能有差异；4）缓存：部署后可能有短暂的旧版本缓存，等待1-2分钟或强制刷新；5）API Key权限：prod环境的API Key可能没有对应模型的调用权限。排查：1）agentkit config show --env prod确认生产配置；2）确认build和deploy的是最新代码；3）agentkit logs --env prod查看生产日志中的错误信息。
Q2：本地调试正常，但agentkit test失败，怎么办？
A：测试失败的常见原因和解决：1）断言太严格：测试用例的assert条件太严格，Agent回复有变化就失败。解决：放宽断言（如用"关键词 in response"而不是精确匹配）；2）模型随机性：temperature>0时Agent回复有随机性，同样的问题每次回复可能不同。解决：测试环境设置temperature=0（environments/dev.yaml中配置），或用包含关系断言；3）测试超时：Agent回复慢导致测试超时。解决：agentkit test --timeout 60延长超时时间；4）API Key无效：测试环境的API Key过期或无权限。解决：检查VOLCENGINE_API_KEY环境变量；5）网络问题：测试时网络不通。解决：检查网络连通性。建议：先用agentkit test --mock验证测试框架正常，再用真实模型测试。
Q3：想更新已经部署的Agent，怎么操作？
A：更新流程：1）修改代码（agent.yaml、system-prompt.md等）；2）本地调试验证（agentkit dev）；3）运行测试（agentkit test）；4）重新打包（agentkit build --env prod，版本号自动递增或在agent.yaml中指定version）；5）重新部署（agentkit deploy --env prod，会更新已有Agent，不创建新的）；6）验证（agentkit status确认新版本，curl测试）。如果新版本有问题，回滚：agentkit rollback --version <旧版本号> --env prod。建议：1）每次更新递增版本号（语义化版本）；2）更新前记录当前版本号，便于回滚；3）重大更新先部署到staging环境验证，再部署prod；4）更新后查看agentkit logs确认无错误。
Q4：Basic Agent模板能加工具和知识库吗？还是必须换模板？
A：Basic Agent模板可以扩展工具和知识库，不需要换模板。Basic模板是"最小可用"的起点，你可以在它基础上逐步添加能力：1）加工具：在agent.yaml的tools字段添加工具配置，在tools/目录写工具代码；2）加知识库：在agent.yaml的knowledge字段添加知识库文件路径，把文档放到knowledge/目录；3）加工作流：复杂流程可以在flows/目录定义工作流。Basic模板的好处是结构简单，容易理解，适合入门后逐步扩展。如果你一开始就知道需要复杂能力（多工具、RAG、工作流），也可以直接用--template tool-agent或--template rag-agent模板，它们预置了对应结构。建议：入门用Basic，熟悉后再扩展；有明确需求直接用对应模板。

[7] 相关阅读

AgentKit CLI安装教程，https://www.volcengine.com/docs/，环境准备和安装步骤
agent.yaml配置规范，https://www.volcengine.com/docs/，配置文件参数全解析
AgentKit CLI预置模板详解，https://www.volcengine.com/docs/，不同模板的选择
AgentKit CLI构建部署，https://www.volcengine.com/docs/，build/deploy命令详解
火山引擎方舟平台文档，https://www.volcengine.com/docs/，推理接入点创建和管理

[8] 参考资料

[1] 火山引擎官方文档 - AgentKit CLI：支持Basic Agent模板，从初始化到部署的全生命周期管理，https://www.volcengine.com/docs/search?q=使用CLI（Agent），2026-08-27
本文基于火山引擎官方文档（2026年8月）和AgentKit CLI Basic Agent实战编写。工具版本更新较快，具体命令请以官方最新文档为准。

[9] 时间

2026-08-27

AgentKit CLI快速入门：Basic Agent模板从开发到部署实战

[1] 一句话结论 #

[2] 适用场景与不适用场景 #