Agent 使用教程

Agent 是 Sira AI 的核心组件，代表具备特定能力的 AI 智能体。本教程将详细讲解如何创建、配置和管理 Agent。

Agent 是什么？

Agent 是一个配置了以下要素的 AI 智能体：

Agent = LLM 模型 + 系统提示词 + MCP 工具 + 知识库 + 配置参数

Agent 的组成

组件	说明	必需
LLM 模型	使用的AI模型（GPT-4o, Claude等）	✅ 必需
系统提示词	定义Agent的角色、能力和行为规范	✅ 必需
MCP 工具	外部工具调用能力（搜索、数据查询等）	⭕ 可选
知识库	RAG检索增强（企业文档、FAQ等）	⭕ 可选
模型参数	temperature, max_tokens等调优参数	⭕ 可选

Agent 的特点

独立执行：可以单独工作，也可以协作
可复用：一个Agent可以被多个Orchestrator使用
可组合：多个Agent可以组合成复杂的系统
专业化：每个Agent专注于特定领域或任务

创建第一个 Agent

步骤 1：进入 Agent 管理

登录 Sira AI 管理后台
点击左侧菜单 Agent System → Agents
点击右上角 创建 Agent 按钮

步骤 2：填写基本信息

名称（Name）

用途：系统内部标识，用于API调用
规则：
- 只能包含字母、数字、下划线
- 不能以数字开头
- 长度 3-50 字符
示例：customer_service, tech_expert, sales_assistant

显示名称（Display Name）

用途：用户看到的友好名称
规则：支持中文、英文，20字符以内
示例：客服助手、技术专家、销售顾问

描述（Description）

用途：说明Agent的职责和能力
建议：简洁明了，100字以内

示例：

专业的客户服务助手，负责回答用户咨询、
处理常见问题、引导用户使用产品功能。

步骤 3：配置系统提示词

系统提示词是 Agent 的"灵魂"，定义了它的角色和行为。

提示词模板

你是 [角色定位]。

【职责范围】
- 职责1
- 职责2
- 职责3

【行为规范】
- 始终保持 [态度]
- 必须遵守 [规则]
- 禁止进行 [限制]

【专业知识】
- 了解 [领域知识]
- 熟悉 [业务流程]

【输出格式】
- 使用 [格式要求]
- 结构化组织内容

示例 1：客服助手

你是一个专业的客户服务助手。

【职责范围】
- 回答用户关于产品功能、使用方法的问题
- 处理常见问题和故障排查
- 引导用户完成操作流程
- 收集用户反馈和建议

【行为规范】
- 始终保持礼貌、耐心、专业的态度
- 使用简单易懂的语言，避免专业术语
- 如果不确定答案，诚实告知并引导联系人工客服
- 不要承诺无法实现的功能或优惠

【回复格式】
- 简洁明了，避免冗长
- 必要时使用分点列表
- 提供操作步骤时使用编号

【特殊情况处理】
- 用户投诉：表示理解，记录问题，引导联系专员
- 技术故障：尝试基本排查，无法解决则转人工
- 价格咨询：提供官网信息，具体优惠请咨询销售

示例 2：技术专家

你是一个资深的软件工程技术专家。

【专业领域】
- 前端开发（React, Vue, Next.js）
- 后端开发（Node.js, Python, Go）
- 云原生架构（Kubernetes, Docker, Serverless）
- 数据库设计（MySQL, PostgreSQL, Redis）

【回答风格】
- 提供技术深度和广度兼备的回答
- 引用官方文档和最佳实践
- 给出可执行的代码示例
- 分析不同方案的优缺点

【格式要求】
- 技术概念要清晰解释
- 代码示例要完整可运行
- 提供相关文档链接
- 总结关键要点

【使用工具】
- 使用 Context7 查询最新技术文档
- 使用 WebSearch 搜索最新技术动态

示例 3：数据分析专家

你是一个数据分析专家，擅长从数据中提取洞察。

【核心能力】
- SQL 查询和数据提取
- 数据清洗和预处理
- 统计分析和可视化
- 业务指标解读

【分析流程】
1. 理解业务问题
2. 确定数据需求
3. 编写 SQL 查询
4. 分析数据结果
5. 提供业务建议

【输出格式】
- 数据发现：关键数据点和趋势
- 可视化建议：适合的图表类型
- 业务洞察：数据背后的含义
- 行动建议：基于数据的决策建议

【工具使用】
- 使用 database_query 工具查询数据
- 使用 chart_generator 工具生成图表

步骤 4：选择 AI 模型

查看可用模型

点击 AI 模型 下拉框，查看已配置的模型列表：

GPT-4o（推荐）
GPT-3.5-turbo
Claude 3.5 Sonnet
DeepSeek Chat
通义千问

选择模型类型

根据 Agent 的功能需求勾选模型类型。实际支持 4 种：

LLM：标准语言模型（必选）
VISION：图片分析（让 Agent 看图）
EMBEDDING：向量化（用于知识库检索）
RERANK：检索结果重排（提升 RAG 准确率）

示例配置：

yaml

# 客服助手（纯文本）
模型类型: [LLM]

# 图片分析助手
模型类型: [LLM, VISION]

# 接入知识库的 Agent（向量化由 KB 内部处理，Agent 通常只配 LLM）
模型类型: [LLM]
knowledge_base_ids: [<kb-uuid>]

没有 CODE / REASONING 类型

旧文档列过 CODE / REASONING 类型——代码里不存在。"擅长代码"或"擅长推理"是模型本身的特性（选 GPT-4o / Claude 3.5 Sonnet / DeepSeek-Coder 等），不是 model_types 字段的值。

步骤 5：配置 MCP 工具（可选）

MCP 工具让 Agent 可以调用外部能力。

查看可用工具

在 MCP 工具 部分，勾选需要的工具：

工具	用途	适用场景
Context7	查询最新技术文档	技术助手、文档查询
WebSearch	网页搜索	实时信息查询
Weather	天气查询	天气助手
Calculator	数学计算	数据计算
Database	数据库查询	数据分析

工具选择建议

不要贪多：

❌ 选择所有工具（Agent会混乱）
✅ 只选择必要的工具（提高准确性）

按需配置：

yaml

# 技术文档助手
工具: [Context7, WebSearch]

# 数据分析助手
工具: [Database, Calculator]

# 简单客服（无工具）
工具: []

步骤 6：关联知识库（可选）

如果有企业文档需要AI检索：

先在 Knowledge Bases 创建知识库
上传文档（PDF、Word、Markdown）
在Agent配置中勾选知识库

效果：

Agent 会自动从知识库检索相关内容
基于企业文档回答问题
提高答案的准确性和专业性

步骤 7：高级配置（可选）

Temperature（创造性）

控制回复的随机性和创造性：

值	效果	适用场景
0.0	确定性强，重复性高	客服问答、技术文档
0.3	较为确定，略有变化	标准流程、教程
0.7	平衡创造性和准确性	通用对话
1.0	高度创造性	创意写作、头脑风暴

推荐值：

yaml

客服助手: 0.3
技术专家: 0.5
创意助手: 0.8

Max Tokens（最大长度）

限制单次回复的最大长度：

yaml

简短回复: 500
标准回复: 1000-2000
详细回复: 3000-4000

注意：Token 越多，成本越高，响应越慢。

Top P（核采样）

控制词汇选择的多样性：

0.1：保守，使用高概率词汇
0.9：多样，探索更多可能性

通常使用默认值 1.0 即可。

步骤 8：保存和测试

点击保存按钮
保存成功后，点击 测试对话 图标
输入测试消息，查看Agent回复
根据效果调整配置

Agent 管理

查看 Agent 列表

Agent 列表显示所有已创建的 Agent：

列	说明
名称	Agent 标识
显示名称	用户友好名称
模型	使用的AI模型
工具数量	配置的MCP工具数量
状态	启用/禁用
操作	编辑/删除/测试

编辑 Agent

在列表中找到要编辑的Agent
点击编辑图标
修改配置
点击保存

注意：编辑Agent会影响所有使用该Agent的Orchestrator。

复制 Agent

快速创建相似的Agent：

点击 Agent 的复制图标
系统创建一个副本（名称添加 _copy）
编辑副本，调整配置
保存

删除 Agent

点击删除图标
确认删除

警告：

❌ 被Orchestrator使用的Agent无法删除
✅ 需要先解除Orchestrator关联

启用/禁用 Agent

临时禁用Agent而不删除：

点击状态开关
禁用后，使用该Agent的Orchestrator会报错
可以随时重新启用

Agent 最佳实践

1. 系统提示词设计

✅ 好的提示词

你是客服助手，负责回答用户关于产品功能的问题。

【职责】
- 回答产品功能咨询
- 引导用户使用产品
- 收集用户反馈

【规范】
- 礼貌专业
- 简洁明了
- 不确定时引导人工

【限制】
- 不做价格承诺
- 不处理退款
- 不泄露内部信息

特点：

角色清晰
职责明确
有规范和限制
结构化组织

❌ 不好的提示词

你是一个AI助手，尽力回答用户的所有问题。

问题：

角色模糊
职责不清
没有规范
没有限制

2. 工具配置策略

按需配置

yaml

# ✅ 技术助手：只配置技术相关工具
工具: [Context7, WebSearch]

# ❌ 技术助手：配置了不相关的工具
工具: [Context7, WebSearch, Weather, Calculator, Database]

工具冲突处理

如果多个工具功能重叠：

优先使用更专业的工具
在提示词中明确使用规则

【工具使用规则】
- 查询技术文档：优先使用 Context7
- 查询新闻资讯：使用 WebSearch
- 数据计算：使用 Calculator

3. 模型选择建议

任务类型	推荐模型	理由
简单问答	GPT-3.5, DeepSeek	成本低，速度快
复杂分析	GPT-4o, Claude 3.5	能力强，准确度高
图片处理	GPT-4o, Qwen-VL	支持 Vision
代码生成	GPT-4o, Claude 3.5	代码质量高
中文优化	通义千问, DeepSeek	中文理解好，成本低
深度推理	DeepSeek R1, GPT-4o	推理能力强

4. 参数调优

Temperature 调优

yaml

# 测试不同 temperature 的效果
Temperature 0.0:
  输入: "介绍一下 React"
  输出: "React 是由 Facebook 开发的..."（每次相同）

Temperature 0.7:
  输入: "介绍一下 React"
  输出: "React 是一个流行的..."（每次略有不同）

Temperature 1.0:
  输入: "介绍一下 React"
  输出: "React 作为现代前端..."（变化较大）

建议：

从 0.7 开始测试
根据实际效果调整
专业领域降低 temperature

Max Tokens 调优

观察Agent的典型回复长度：

bash

# 短回复（100-300 tokens）
用户: "今天天气如何？"
Agent: "今天晴天，温度25°C。"

# 中等回复（500-1000 tokens）
用户: "如何配置 Agent？"
Agent: "配置Agent需要以下步骤：1. 进入管理后台..."

# 长回复（2000+ tokens）
用户: "详细介绍编排模式"
Agent: "Sira AI 支持 8 种编排模式：【Single 模式】..."

设置建议：

观察Agent回复长度
Max Tokens = 平均长度 × 1.5
避免设置过大（成本高）

5. Agent 专业化

单一职责原则

✅ 好的设计：

Agent 1: 技术咨询（只回答技术问题）
Agent 2: 价格咨询（只回答价格问题）
Agent 3: 售后服务（只处理售后问题）

❌ 不好的设计：

Agent: 万能助手（什么都回答，但都不专业）

专业领域细分

yaml

# 粗粒度（不推荐）
Agent: IT专家

# 细粒度（推荐）
Agent 1: 前端开发专家（React/Vue）
Agent 2: 后端开发专家（Node.js/Python）
Agent 3: DevOps 专家（Docker/K8s）
Agent 4: 数据库专家（MySQL/Redis）

Agent 测试

单Agent测试

方法 1：界面测试

在Agent列表点击测试图标
输入测试消息
观察回复质量
调整配置后重新测试

方法 2：API测试

bash

curl -X POST http://localhost:8000/api/agent-system/agents/{agent_id}/test \
  -H "Content-Type: application/json" \
  -d '{
    "message": "你好，请介绍一下你的功能"
  }'

测试检查清单

基础功能

[ ] Agent 能正常回复
[ ] 回复符合角色设定
[ ] 语言风格一致
[ ] 回复长度合适

专业能力

[ ] 回答准确
[ ] 知识全面
[ ] 引用可靠
[ ] 逻辑清晰

行为规范

[ ] 遵守角色限制
[ ] 拒绝越权请求
[ ] 正确处理敏感信息
[ ] 引导用户合理使用

工具使用

[ ] 正确识别需要使用工具的场景
[ ] 正确调用工具
[ ] 正确解读工具返回结果
[ ] 工具失败时有fallback

测试用例示例

客服助手测试

yaml

测试用例 1: 基础问答
  输入: "你们的产品有什么功能？"
  期望: 列举主要功能，简洁明了

测试用例 2: 操作指导
  输入: "如何创建 Agent？"
  期望: 分步骤说明，清晰易懂

测试用例 3: 边界处理
  输入: "能给我打个折吗？"
  期望: 礼貌拒绝，引导咨询销售

测试用例 4: 异常处理
  输入: "系统崩溃了怎么办？"
  期望: 收集信息，引导联系技术支持

技术专家测试

yaml

测试用例 1: 技术咨询
  输入: "React 和 Vue 有什么区别？"
  期望: 客观对比，列举优缺点

测试用例 2: 代码示例
  输入: "如何使用 useState？"
  期望: 提供完整可运行的代码示例

测试用例 3: 工具使用
  输入: "查询 Next.js 14 的新特性"
  期望: 调用 Context7，返回最新文档信息

测试用例 4: 复杂问题
  输入: "如何优化 React 应用性能？"
  期望: 多角度分析，提供具体方案

常见问题

Q1: Agent 回答太长或太短？

解决方案：

调整 max_tokens 参数

在提示词中明确要求：

【回复要求】
- 简洁明了，不超过200字
- 必要时使用分点列表

Q2: Agent 不使用配置的工具？

排查步骤：

检查工具是否启用

检查提示词是否提到工具：

【可用工具】
- Context7：查询技术文档
- WebSearch：搜索网页信息

【工具使用规则】
- 遇到技术问题，优先使用 Context7

测试工具是否可用
查看日志，确认工具调用情况

Q3: Agent 回答不在角色范围内？

解决方案：

强化提示词的限制部分：

【严格限制】
- 只回答产品相关问题
- 不回答价格和优惠
- 不处理退款和投诉
- 超出范围时，明确告知并引导

【示例拒绝话术】
用户: "能给我打个折吗？"
回复: "非常抱歉，价格和优惠相关问题请咨询我们的销售顾问..."

Q4: 多个Agent回答风格不统一？

解决方案：

创建统一的提示词模板：

【团队规范】（所有Agent共享）
- 使用规范的中文表达
- 避免使用网络用语和表情符号
- 保持专业和礼貌
- 回复结构化、条理清晰

【格式规范】
- 标题使用【】
- 列表使用 - 或数字编号
- 代码使用```包裹

Q5: Agent 回答过时信息？

解决方案：

启用 MCP 工具（如 WebSearch）查询实时信息
定期更新知识库内容

在提示词中强调：

【信息时效性】
- 优先使用工具查询最新信息
- 如果不确定信息是否最新，明确告知用户
- 提供信息来源和时间

进阶技巧

1. 多Agent协同设计

设计互补的Agent团队：

yaml

Agent 团队: 客户服务系统

Agent 1: 路由助手
  作用: 识别问题类型，分配到专家
  提示词: "你是问题分类专家，识别用户问题属于技术/销售/售后"

Agent 2: 技术专家
  作用: 回答技术问题
  工具: [Context7, WebSearch]

Agent 3: 销售专家
  作用: 回答价格和购买问题
  知识库: [价格表, 产品介绍]

Agent 4: 售后专家
  作用: 处理退换货和投诉
  工具: [工单系统]

2. Few-Shot Learning

在提示词中提供示例：

【示例对话】

示例 1:
用户: "如何重置密码？"
回复: "重置密码的步骤如下：
1. 打开登录页面
2. 点击"忘记密码"
3. 输入注册邮箱
4. 查收验证码邮件
5. 输入验证码并设置新密码"

示例 2:
用户: "能给我个优惠码吗？"
回复: "非常抱歉，我这边无法提供优惠码。请关注我们的官方公众号或联系销售顾问获取最新优惠信息。"

3. 上下文控制

每个 Agent 有 memory_type 字段，当前两种取值：

Type	行为
`none`	不接 Checkpointer，每次对话独立
`summarize_at_limit`（默认）	LangGraph RedisCheckpointer + 自动摘要中间件，接近模型 context window 的 15% 时触发摘要

Redis 中按 thread_id（= session_id）存对话历史，TTL 24 小时。同一会话 24 小时内回到同一 session_id 仍能续上。

没有"短期 / 长期"枚举

旧文档描述过 "短期记忆 / 长期记忆"、"按用户历史" 这类配置——代码里不存在。Migration 014 已经把 5 种记忆类型简化到 2 种。详见记忆管理。

下一步

掌握Agent创建后，继续学习：

Orchestrator 配置指南 - 编排多个Agent协同工作
Application 接入指南 - 将Agent暴露给用户使用
MCP 工具使用 - 让Agent使用外部工具
完整使用场景 - 实际应用案例

💡 提示：

Agent 设计是一门艺术，需要不断测试和优化
从简单开始，逐步增加复杂性
观察用户反馈，持续改进提示词
善用工具和知识库增强Agent能力

Agent 使用教程 ​

Agent 是什么？ ​

Agent 的组成 ​

Agent 的特点 ​

创建第一个 Agent ​

步骤 1：进入 Agent 管理 ​

步骤 2：填写基本信息 ​

名称（Name） ​

显示名称（Display Name） ​

描述（Description） ​

步骤 3：配置系统提示词 ​

提示词模板 ​

示例 1：客服助手 ​

示例 2：技术专家 ​

示例 3：数据分析专家 ​

步骤 4：选择 AI 模型 ​

查看可用模型 ​

选择模型类型 ​

步骤 5：配置 MCP 工具（可选） ​

查看可用工具 ​

工具选择建议 ​

步骤 6：关联知识库（可选） ​

步骤 7：高级配置（可选） ​

Temperature（创造性） ​

Max Tokens（最大长度） ​

Top P（核采样） ​

步骤 8：保存和测试 ​

Agent 管理 ​

查看 Agent 列表 ​

编辑 Agent ​

复制 Agent ​

删除 Agent ​

启用/禁用 Agent ​

Agent 最佳实践 ​

1. 系统提示词设计 ​

✅ 好的提示词 ​

❌ 不好的提示词 ​

2. 工具配置策略 ​

按需配置 ​

工具冲突处理 ​

3. 模型选择建议 ​

4. 参数调优 ​

Temperature 调优 ​

Max Tokens 调优 ​

5. Agent 专业化 ​

单一职责原则 ​

专业领域细分 ​

Agent 测试 ​

单Agent测试 ​

方法 1：界面测试 ​

方法 2：API测试 ​

测试检查清单 ​

基础功能 ​

专业能力 ​

行为规范 ​

工具使用 ​

测试用例示例 ​

客服助手测试 ​

技术专家测试 ​

常见问题 ​

Q1: Agent 回答太长或太短？ ​

Q2: Agent 不使用配置的工具？ ​

Q3: Agent 回答不在角色范围内？ ​

Q4: 多个Agent回答风格不统一？ ​

Q5: Agent 回答过时信息？ ​

进阶技巧 ​

1. 多Agent协同设计 ​

2. Few-Shot Learning ​

3. 上下文控制 ​

下一步 ​

Agent 使用教程

Agent 是什么？

Agent 的组成

Agent 的特点

创建第一个 Agent

步骤 1：进入 Agent 管理

步骤 2：填写基本信息

名称（Name）

显示名称（Display Name）

描述（Description）

步骤 3：配置系统提示词

提示词模板

示例 1：客服助手

示例 2：技术专家

示例 3：数据分析专家

步骤 4：选择 AI 模型

查看可用模型

选择模型类型

步骤 5：配置 MCP 工具（可选）

查看可用工具

工具选择建议

步骤 6：关联知识库（可选）

步骤 7：高级配置（可选）

Temperature（创造性）

Max Tokens（最大长度）

Top P（核采样）

步骤 8：保存和测试

Agent 管理

查看 Agent 列表

编辑 Agent

复制 Agent

删除 Agent

启用/禁用 Agent

Agent 最佳实践

1. 系统提示词设计

✅ 好的提示词

❌ 不好的提示词

2. 工具配置策略

按需配置

工具冲突处理

3. 模型选择建议

4. 参数调优

Temperature 调优

Max Tokens 调优

5. Agent 专业化

单一职责原则

专业领域细分

Agent 测试

单Agent测试

方法 1：界面测试

方法 2：API测试

测试检查清单

基础功能

专业能力

行为规范

工具使用

测试用例示例

客服助手测试

技术专家测试

常见问题

Q1: Agent 回答太长或太短？

Q2: Agent 不使用配置的工具？

Q3: Agent 回答不在角色范围内？

Q4: 多个Agent回答风格不统一？

Q5: Agent 回答过时信息？

进阶技巧

1. 多Agent协同设计

2. Few-Shot Learning

3. 上下文控制

下一步