AgentKit CLI预置模板详解：基础Agent/流式输出Agent/工具调用Agent怎么选

数据老陈

2026-8-31

[1] 一句话结论

AgentKit CLI预置4类模板：基础Agent入门用、流式输出Agent对话体验用、工具调用Agent扩展能力用、RAG Agent知识库用，按需选择。

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

适用场景

你在用agentkit init创建项目时，发现可以选--template参数，有多个预置模板可选。但你不确定每个模板的区别、适用场景、生成的项目结构有什么不同，不知道该选哪个。选错了模板可能要花时间改造，或者模板太复杂看不懂。
这篇文章详解AgentKit CLI的所有预置模板，从模板定位、项目结构、核心能力、适用场景到选择建议，帮你在创建项目时选对模板，少走弯路。
适合：第一次用AgentKit CLI创建项目的开发者、想了解不同模板差异的技术人员、需要为团队选择标准模板的技术负责人。

不适用场景

已经选好模板并在开发的用户：本文是选型指南，已开发的用户参考价值有限。
想深度定制模板的用户：本文介绍预置模板，自定义模板参考官方开发文档。
非技术用户：模板选择是开发者操作，非技术用户可以用默认模板。

[3] 前置准备

AgentKit CLI已安装（agentkit --version确认）
对Agent的基本概念有了解（提示词、工具、知识库）
预计耗时：阅读6分钟

[4] 分步实现

步骤1：预置模板总览

执行agentkit init --help查看所有可用模板：

agentkit init --help

输出中--template参数的可选值：

模板名	定位	复杂度	适合人群
basic	基础对话Agent，最小可用	⭐ 最简单	入门新手、简单对话场景
streaming	流式输出Agent，SSE响应	⭐⭐ 简单	需要实时输出效果的对话应用
tool-agent	工具调用Agent，含示例工具	⭐⭐⭐ 中等	需要Agent调用外部API/执行操作
rag	知识库Agent，RAG检索增强	⭐⭐⭐ 中等	需要基于私有文档回答的场景
full	全功能Agent，工具+知识库+工作流	⭐⭐⭐⭐ 复杂	复杂企业级Agent，需要全部能力
custom	空白模板，从零开始	⭐⭐ 自定义	有明确需求，想完全自定义结构

默认模板：不指定--template时，默认使用basic模板。

选择原则：从简单开始，需要什么能力再加什么。不要一开始就选full模板，结构太复杂可能看不懂。建议：入门用basic，需要特定能力时选对应模板，或在basic基础上逐步扩展。

步骤2：basic模板详解

定位：最简单的对话Agent，最小可用的项目结构，适合入门和简单对话场景。
创建命令：

agentkit init my-agent --template basic

项目结构：

my-agent/
├── agent.yaml              # 基础配置（名称、模型、提示词引用）
├── system-prompt.md        # 系统提示词
├── tests/
│   └── test_agent.py       # 基础测试
├── environments/
│   ├── dev.yaml
│   └── prod.yaml
├── requirements.txt        # 仅agentkit-cli依赖
├── .gitignore
└── README.md

核心能力：

单轮/多轮对话
系统提示词定义角色
模型参数配置
基础测试框架
不含：工具、知识库、工作流、流式输出（可后续添加）
适用场景：
第一次接触AgentKit CLI，学习基本流程
简单的对话助手（如客服问答、编程助手、翻译工具）
不需要调用外部工具和知识库的纯对话场景
快速原型验证
团队培训和Demo
优点：结构简单，容易理解，文件少，上手快。
缺点：能力有限，需要工具/知识库时要自己加。

适合人群：80%的入门场景都可以从basic开始。熟悉后再扩展工具和知识库，比一开始用复杂模板更容易掌握。

步骤3：streaming模板详解

定位：支持流式输出（SSE）的对话Agent，回复逐字显示，提升用户体验。
创建命令：

agentkit init my-agent --template streaming

项目结构（在basic基础上增加）：

my-agent/
├── agent.yaml              # 配置中stream: true
├── system-prompt.md
├── server.py               # SSE流式服务器（新增）
├── static/
│   └── index.html          # 流式对话前端页面（新增）
├── tests/
│   └── test_streaming.py   # 流式输出测试（新增）
├── environments/
├── requirements.txt        # 增加sse-starlette等依赖
└── README.md

核心能力：

basic的全部能力
SSE（Server-Sent Events）流式输出，回复逐字显示
内置简单的Web对话界面（static/index.html）
流式服务器（server.py，基于FastAPI+SSE）
agent.yaml关键配置：

model:
  provider: volcengine
  model_id: ep-xxxxxxxx
  stream: true              # 启用流式输出
deploy:
  server:
    type: sse
    path: ./server.py

适用场景：

面向用户的对话应用（用户等待时看到逐字输出，体验更好）
需要嵌入Web页面的Agent（内置前端页面可直接用）
长文本生成场景（流式输出减少等待焦虑）
Chatbot、智能客服、写作助手
优点：用户体验好，回复即时可见，内置Web界面可直接部署。
缺点：比basic多了服务器和前端代码，稍复杂。

注意：流式输出需要模型支持stream模式。火山方舟的豆包系列模型都支持流式。如果用自定义模型，确认API支持SSE。

步骤4：tool-agent模板详解

定位：预置工具调用能力的Agent，包含示例工具代码，适合需要Agent调用外部API/执行操作的场景。
创建命令：

agentkit init my-agent --template tool-agent

项目结构（在basic基础上增加）：

my-agent/
├── agent.yaml              # tools字段配置了示例工具
├── system-prompt.md        # 提示词中说明了工具使用规范
├── tools/                  # 工具目录（新增）
│   ├── __init__.py
│   ├── weather.py          # 示例：天气查询工具（HTTP API）
│   ├── calculator.py       # 示例：计算器工具（本地函数）
│   └── web_search.py       # 示例：网页搜索工具（内置工具封装）
├── tests/
│   └── test_tools.py       # 工具调用测试（新增）
├── environments/
├── requirements.txt        # 增加requests等工具依赖
└── README.md

核心能力：

basic的全部能力
3个示例工具（天气查询、计算器、网页搜索）
工具开发规范（@tool装饰器、参数注解、docstring）
工具调用测试框架
系统提示词中包含工具使用规范
agent.yaml关键配置：

tools:
  - name: weather_query
    type: python
    path: ./tools/weather.py
    enabled: true
    config:
      api_key: ${WEATHER_API_KEY}
  - name: calculator
    type: python
    path: ./tools/calculator.py
    enabled: true
  - name: web_search
    type: builtin
    enabled: true

适用场景：

需要Agent调用外部API（如查天气、查股票、调内部系统）
需要Agent执行本地操作（如计算、文件处理、数据转换）
需要Agent联网搜索信息
智能助手、自动化工具、业务流程Agent
优点：预置示例工具，照着写就能开发自己的工具，少踩坑。
缺点：工具代码需要Python基础，比basic复杂。

工具开发要点：1）照着示例工具的格式写（@tool装饰器+类型注解+docstring）；2）工具description要详细，Agent靠这个判断何时调用；3）不需要的示例工具可以删掉（enabled: false或直接删文件）；4）工具内部做好错误处理，返回友好错误信息。

步骤5：rag模板详解

定位：预置知识库（RAG）能力的Agent，支持文档上传、向量化、检索增强生成。
创建命令：

agentkit init my-agent --template rag

项目结构（在basic基础上增加）：

my-agent/
├── agent.yaml              # knowledge字段配置了知识库
├── system-prompt.md        # 提示词中说明"基于知识库回答"
├── knowledge/              # 知识库目录（新增）
│   ├── docs/               # 文档存放处
│   │   ├── product.md      # 示例文档
│   │   └── faq.md          # 示例FAQ
│   └── .gitkeep
├── tests/
│   └── test_rag.py         # RAG检索测试（新增）
├── environments/
├── requirements.txt        # 增加向量数据库、嵌入模型依赖
└── README.md

核心能力：

basic的全部能力
文件型知识库（自动分块、向量化、检索）
2个示例文档（产品介绍、FAQ）
RAG检索测试框架
系统提示词中包含"基于知识库回答，不知道就说不知道"
agent.yaml关键配置：

knowledge:
  - name: product_kb
    type: file
    path: ./knowledge/docs/
    enabled: true
    config:
      chunk_size: 512
      chunk_overlap: 50
      embedding_model: doubao-embedding
      top_k: 3
prompt:
  system: ./system-prompt.md
  # 提示词中应包含："请基于知识库内容回答，如果知识库中没有相关信息，请明确说不知道"

适用场景：

企业知识库问答（产品文档、技术文档、规章制度）
客服FAQ自动回答
私人知识库助手（笔记、书籍、论文问答）
文档摘要和信息提取
减少模型幻觉（基于真实文档回答）
优点：预置RAG流程，放文档就能用，不需要自己实现检索逻辑。
缺点：知识库构建需要时间（首次向量化），大文档可能耗时。

RAG效果优化：1）文档质量决定回答质量，确保文档清晰、准确、结构化；2）chunk_size 512、overlap 50是常用配置，可根据文档类型调整；3）top_k 3-5，太小漏检太大噪声；4）系统提示词明确要求"基于知识库回答"，否则Agent可能用模型自带知识回答。

步骤6：full和custom模板

full模板（全功能）：

定位：包含工具+知识库+工作流+流式输出的全功能Agent
适合：复杂企业级Agent，确定需要全部能力
项目结构：包含tools/、knowledge/、flows/、server.py、static/等所有目录
注意：结构复杂，文件多，新手可能看不懂。建议先从basic/tool-agent/rag开始，需要时再逐步扩展到full的能力。
custom模板（空白）：
定位：最小化的空白项目，只有agent.yaml和基本目录，完全自定义
适合：有明确的项目结构需求，想完全自己控制
创建：agentkit init my-agent --template custom
注意：需要自己创建所有文件和配置，适合有经验的开发者。

步骤7：模板选择决策和扩展

选择决策流程：

你需要Agent做什么？
├─ 简单对话（问答、聊天、翻译）→ basic
├─ 面向用户的对话应用（要逐字输出）→ streaming
├─ 需要调用外部API/执行操作 → tool-agent
├─ 需要基于私有文档回答 → rag
├─ 以上都需要（复杂企业级）→ full
└─ 有特殊结构需求 → custom

模板可以互相扩展：

basic + 加工具 = tool-agent的能力
basic + 加知识库 = rag的能力
tool-agent + 加知识库 = 接近full
任何模板 + stream: true = 流式输出
所以不需要纠结选哪个，从basic开始，需要什么加什么，逐步扩展即可。AgentKit的设计就是"渐进式增强"。
切换模板：
已经创建了项目想换模板？不能直接转换，但可以：1）新建项目用目标模板，把代码/配置迁移过去；2）在现有项目中手动添加缺少的目录和配置（参考目标模板的结构）。建议：创建前先想清楚需求，选最接近的模板，减少后续改造。

[5] 实际验证

理解模板后验证：测试1 用basic模板创建项目，确认结构最简单，能跑通对话；测试2 用tool-agent模板创建项目，确认tools/目录有示例工具，调试界面能看到工具；测试3 用rag模板创建项目，确认knowledge/目录有示例文档，能基于文档回答；测试4 用streaming模板创建项目，启动后确认回复是逐字流式输出；测试5 根据你的项目需求，用决策流程选出推荐模板。成功标志：能说清每个模板的区别和适用场景，并为自己的项目选出合适的模板。

[6] 常见问题 FAQ

Q1：选了basic模板，后来需要加工具和知识库，要重新创建项目吗？
A：不需要重新创建。AgentKit支持渐进式扩展，在basic项目中直接添加即可：1）加工具：创建tools/目录，写工具代码（参考tool-agent模板的示例），在agent.yaml的tools字段添加配置；2）加知识库：创建knowledge/目录，放文档，在agent.yaml的knowledge字段添加配置；3）加流式输出：在agent.yaml的model字段加stream: true，创建server.py（参考streaming模板）；4）加工作流：创建flows/目录，定义工作流，在agent.yaml的flow字段启用。所有模板的能力都是通过agent.yaml配置+对应目录文件实现的，不是模板特有的。所以从basic开始，需要什么加什么，是最灵活的方式。建议：不要因为"以后可能需要"就一开始选full，先basic跑通，再按需扩展。
Q2：可以修改预置模板吗？想创建自己的团队标准模板
A：可以。有两种方式：1）基于预置模板修改：用某个模板创建项目，修改成团队需要的标准结构（加团队规范、通用工具、标准配置），然后作为团队的"种子项目"。新人用这个种子项目复制开始开发；2）自定义模板（高级）：AgentKit CLI支持--template参数指定本地路径或Git仓库，如agentkit init my-agent --template ./my-custom-template或--template git+https://github.com/team/template.git。你可以创建自己的模板仓库，包含团队标准的目录结构、配置、工具、CI/CD脚本等，团队成员用--template指定你的模板即可。建议：团队有3人以上且都在用AgentKit时，值得维护一个团队标准模板，统一规范、减少重复配置。
Q3：full模板太复杂看不懂，怎么办？
A：full模板确实文件多、结构复杂，不建议新手直接用。解决方法：1）从basic开始，先理解最小项目结构（agent.yaml + system-prompt.md）；2）需要工具时，创建一个最简单的工具（如calculator），理解工具的注册和调用机制；3）需要知识库时，放一个简单文档，理解RAG的检索流程；4）逐个能力理解后，再看full模板就会发现它只是把所有能力放在一起，每个部分你都已经理解了；5）也可以参考官方文档的"渐进式教程"，从basic逐步添加能力，每步都有解释。建议：学习任何复杂框架都从最小可用开始，不要一上来就看全功能示例。full模板适合作为"参考大全"，需要某个能力时去查对应的部分，而不是作为入门起点。
Q4：模板创建的项目能直接部署到生产吗？
A：模板创建的项目是"开发起点"，部署到生产前需要做一些配置：1）配置生产环境：编辑environments/prod.yaml，填入生产用的API Key、模型ID、实例规格等；2）修改系统提示词：模板自带的系统提示词是示例，需要根据你的业务场景修改；3）替换示例内容：tool-agent的示例工具、rag的示例文档、streaming的示例前端，都需要替换成你的真实内容；4）运行测试：agentkit test确保所有测试通过；5）安全检查：确认所有API Key用环境变量，没有明文写在配置中；6）先部署staging验证，再部署prod。模板的作用是"让你少写样板代码"，不是"创建即生产可用"。建议：把模板当作脚手架，创建后花时间定制成你的项目，再部署。

[7] 相关阅读

AgentKit CLI快速入门，https://www.volcengine.com/docs/，basic模板从开发到部署
agent.yaml配置规范，https://www.volcengine.com/docs/，工具、知识库等配置字段详解
AgentKit CLI工具开发指南，https://www.volcengine.com/docs/，自定义Python工具开发
AgentKit CLI知识库配置，https://www.volcengine.com/docs/，RAG配置和优化
AgentKit CLI构建部署，https://www.volcengine.com/docs/，部署到生产环境

[8] 参考资料

[1] 火山引擎官方文档 - AgentKit CLI：支持basic、streaming、tool-agent、rag、full等预置模板，快速启动Agent开发，https://www.volcengine.com/docs/search?q=使用CLI（Agent），2026-08-27
本文基于火山引擎官方文档（2026年8月）和各预置模板实际使用对比编写。工具版本更新较快，具体模板请以官方最新文档为准。

[9] 时间

2026-08-27

AgentKit CLI预置模板详解：基础Agent/流式输出Agent/工具调用Agent怎么选

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #

步骤1：预置模板总览

步骤2：basic模板详解

步骤3：streaming模板详解

步骤4：tool-agent模板详解

步骤5：rag模板详解

步骤6：full和custom模板

步骤7：模板选择决策和扩展

[5] 实际验证 #

[6] 常见问题 FAQ #

[7] 相关阅读 #

[8] 参考资料 #

[9] 时间 #

[1] 一句话结论

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

[3] 前置准备

[4] 分步实现

[5] 实际验证

[6] 常见问题 FAQ

[7] 相关阅读

[8] 参考资料

[9] 时间