从一个业务任务开始搭建可用 Agent
创建 Agent 不只是新建一个元素。一个真正可用的 Agent 需要有明确的任务边界、合适的大模型、稳定的提示词、必要的工具和知识来源，并经过真实任务验证。
这篇文档提供一条从 0 到可用的主线流程。你可以把它当作 Agent 开发检查清单，先做出一个可验证的版本，再逐步补充记忆、文件空间、权限、隐私保护和程序调用能力。
先选一个边界清楚的业务任务
不要一开始就做“企业全能助手”。更稳妥的做法是选择一个高频、边界清楚、结果容易检查的任务。
适合第一个 Agent 的任务：
- 查询订单、客户、工单等业务数据。
- 根据固定规则生成报表、摘要或处理建议。
- 按用户输入调用服务函数完成一个明确动作。
- 基于知识库回答产品、制度或流程问题。
不适合作为第一个 Agent 的任务：
- 同时覆盖多个部门、多个系统、多个业务目标。
- 需要大量人工判断且没有清晰规则。
- 会直接执行高风险操作，但还没有设计清楚角色权限和业务复核流程。
如果任务需要多个角色协作，可以考虑 DeepAgent；如果任务流程固定、每一步都要可控，可以考虑 FlowAgent。大多数入门场景先使用 ReActAgent。
创建 ReActAgent 并完成基础配置
进入 IDE 后，在元素目录树中依次点击 +、AI Agent、ReActAgent，填写名称后进入编辑器。
创建后先完成三件事：
- 在基础配置中选择主模型。需要调用工具时，主模型必须支持 Function Calling。
- 写清楚能力描述，让开发者和平台都能理解这个 Agent 擅长处理什么任务。
- 编写 System Prompts，明确角色、任务边界、工作步骤和输出要求。
详细创建入口和模型配置见最通用的 ReActAgent。
用提示词定义角色、边界和工作步骤
System Prompts 不宜只写一句“你是某某助手”。建议至少包含四类信息：
- 角色定位：这个 Agent 面向谁，负责哪类任务。
- 适用范围：什么问题应该处理，什么问题应该拒绝或转人工。
- 工作步骤：先确认信息、再查询或分析、最后输出结论。
- 输出要求：回答结构、字段、语气和需要提醒用户补充或复核的内容。
示例：
你是订单处理助手，负责帮助客服查询订单状态、解释物流异常原因，并给出下一步处理建议。
工作步骤：
1. 先确认用户提供的订单号或客户信息。
2. 查询订单状态、物流状态和售后记录。
3. 如果信息不足，先说明缺少哪些信息，不要编造。
4. 输出订单状态、异常原因和建议动作。
约束：
- 不直接承诺退款、赔偿或修改合同条款。
- 涉及金额调整时必须走已配置的权限和业务复核流程。
如果 Agent 需要复用团队已有流程、话术或规则，建议将这些内容沉淀为 Skill，再在 Agent 中安装使用。
只添加完成任务必须使用的工具
Agent 向大模型暴露的工具越多，模型选择工具的负担越大，误调用风险也越高。第一个版本只添加完成目标任务必须使用的工具。
常见工具选择：
| 任务需要 | 推荐配置 |
|---|---|
| 查询或修改业务数据 | 数据模型函数 |
| 执行复杂业务逻辑 | 服务函数 |
| 操作当前页面组件 | 页面函数 |
| 基于文档回答问题 | 知识库 |
| 复用团队流程和输出规范 | Skill |
配置工具时优先使用自定义模式，明确勾选需要暴露给大模型的模型、函数或知识库。添加后继续通过按需向大模型暴露工具函数关闭无关函数。
这一步不是权限配置。上线前仍需要在角色权限中配置 Agent、数据模型和服务函数权限，确保未授权用户即使直接发起调用指令，也会被运行时阻止。
用输入输出配置稳定程序调用
如果 Agent 会被页面函数、服务函数或外部流程调用，建议提前配置输入变量和输出格式。
- 输入变量用于把订单号、客户 ID、日期范围等结构化参数传给 Agent。
- JSON 结构化输出适合后续程序继续处理结果。
- 纯文本输出适合聊天问答和人工阅读。
例如“客户风险分析 Agent”可以定义 customerId、dateRange 两个输入变量，并定义“风险等级、关键依据、建议动作”三个输出字段。详细方法见用输入输出配置让 Agent 可被程序稳定调用。
在真实任务中测试和收敛
不要只问“你是谁”“能做什么”。验证 Agent 时应该使用真实业务任务，并覆盖成功、缺信息、无权限和高风险操作等情况。
建议准备一组测试问题：
- 正常任务：信息完整，Agent 应该能查到数据并输出结果。
- 信息不足：缺订单号、客户 ID 或时间范围，Agent 应该先追问。
- 工具不可用：目标数据不存在或服务函数失败，Agent 应该说明原因。
- 高风险操作：删除、退款、批量修改等，Agent 应该受角色权限约束；无权限时运行时会自动阻止调用。
- 非职责任务：超出 Agent 范围的问题，Agent 应该说明边界。
验证时重点观察四件事：
- 是否在正确场景调用正确工具。
- 输出结构是否稳定。
- 是否遵守提示词、Skill 和权限边界。
- 是否存在不必要的工具调用或过长回答。
上线前补齐安全和体验配置
Agent 初步可用后，再按场景补齐安全、上下文和用户体验配置。
- 面向真实用户使用：配置欢迎语和预置问题，降低首次使用门槛。
- 需要控制 Agent 可见范围、数据模型函数或服务函数权限：配置Agent 访问权限。
- 对话中可能包含手机号、身份证、邮箱等敏感信息：启用隐私保护。
- 长任务或多轮任务：开启自动压缩对话上下文。
- 需要记住用户偏好或历史事实：配置跨会话记忆。
- 需要读取和生成文件：配置Agent 文件空间。
- 需要在页面或服务中触发 Agent：阅读在前后端程序中调用 Agent。
什么时候继续升级 Agent 类型
第一个版本通常先用 ReActAgent。随着任务复杂度增加，可以按下面方式升级：
- 任务需要多角色协作、并行分析、父子任务拆解：升级为 DeepAgent。
- 任务流程固定、节点顺序清楚、需要人工节点或条件分支：升级为 FlowAgent。
- 需要嵌入官网、SaaS 或第三方系统：使用 EmbeddedAgent。
升级前先确认问题出在哪里。很多不稳定并不是 Agent 类型问题，而是任务边界太宽、工具过多、提示词不清楚或缺少真实测试。