搭建 AI Agent
AI Agent（AI 智能体）是 Zion 中可复用的 AI 配置。它接收页面或服务端传入的数据，将提示词、知识库和工具组合后交给大模型处理，并以纯文本、结构化数据或图片等形式返回结果。
如果 Agent 只需要完成一次任务，可以在开始会话后直接使用结果；如果需要连续对话，则保存会话 ID，并使用继续会话、停止回复和删除会话管理后续交互。
适用场景
- 根据用户输入生成、改写或总结内容。
- 结合项目数据回答问题，例如知识问答和智能客服。
- 让大模型按业务需要调用 API、行为流或其他 Agent。
- 返回固定结构的数据，供条件判断、数据库操作或页面展示使用。
- 生成或处理图片、视频等多媒体内容。
配置流程
创建 Agent
打开顶部的行为，进入 Agent，然后创建 Agent 并设置名称。
创建第一个 Agent 时，系统会自动创建会话、消息、消息内容和工具使用记录等数据表，用于保存运行记录。详见运行数据。
选择模型并设置基础参数
选择符合任务要求的大模型。不同模型支持的多模态输入、流式输出、结构化输出、推理内容和工具调用能力可能不同，编辑器会根据所选模型显示可用配置。
常用参数包括：
- 生成内容的随机性：值越高，输出通常越多样；需要稳定、可重复的结果时使用较低值。
- 最大轮数：限制单个会话可以进行的对话轮数。
- 每轮对话消耗的 token 数上限：限制单轮输出；达到上限时，结果可能不完整或本轮调用失败。
- 图片处理模式：在模型支持图片输入时选择处理精度。精细模式通常消耗更多 Token。
多轮会话会携带历史消息。轮数越多、单轮内容越长，发送给模型的上下文和 AI Point 消耗通常越高。
配置输入
输入定义调用 Agent 时可以传入的动态数据，例如用户问题、文章内容、记录 ID 或图片。
- 文本、数字等输入可以在 提示词模板 和 知识库 配置中引用。
- 图片和视频输入会自动附加到提示词内容末尾，不能在提示词文本中插入其变量。
- 输入名称和类型一旦被页面、行为流或 Runtime API 使用，修改后需要同步检查所有调用方。
只把每次调用会变化的数据定义为输入。固定的角色、规则和输出要求应写入系统提示词。
配置提示词模板
- 系统提示词：说明 Agent 的角色、目标、业务规则、限制和输出要求。
- 初始用户消息：定义创建会话时发送的第一条用户消息。部分模型要求此项必填。
提示词应明确任务目标、可使用的信息、不能执行的操作和结果要求。需要引用动态数据时，从数据绑定面板选择已定义的输入，不要手动拼写无法解析的变量路径。
配置知识库
知识库用于在每次调用时检索与当前问题相关的数据，并将检索结果与提示词一起发送给大模型。数据来源可以是 Zion 数据库或 API。
配置知识库时，重点确认：
- 用什么内容执行检索。
- 从哪个数据源和字段中检索。
- 返回多少条结果。
- 数据权限和筛选条件是否会限制当前用户可访问的内容。
自 2025 年 8 月起，不再支持新增直接上传文件的知识库；已有的文件知识库不受影响。需要使用文件内容时，可以预处理后写入 Zion 数据库，或通过第三方 RAG 服务处理后使用 API 获取结果。
向量存储和向量搜索的配置方法请参考使用向量数据。
配置工具
Agent 可以将以下能力作为工具：
- 行为流
- API
- 其他 Agent
大模型会根据当前消息和工具描述，自主判断是否调用工具以及传入什么参数。工具名称和描述应准确说明用途、适用条件、入参和结果，避免多个工具承担相同职责。
工具执行可能产生数据库修改、外部请求或其他副作用。对于创建订单、发送通知等操作，应在工具对应的行为流或 API 中配置权限、参数校验和幂等逻辑，不能只依赖提示词约束。
配置输出
根据结果的使用方式选择输出类型：
- 纯文本：适合直接展示自然语言内容，并可开启流式输出。
- 结构化：按配置的字段返回数据，适合后续绑定、判断或写入数据库。字段名称应使用稳定的英文变量名，并为每个字段补充清晰描述。
并非所有模型都支持流式输出或结构化输出。切换模型后，应重新检查输出配置并再次调试。
流式内容只能用于页面展示，不能在生成过程中作为项目数据继续流转。Agent 完成后，可以在 成功时 分支中使用完整结果。
调试 Agent
在 调试 中填写本次测试所需的输入，并运行 Agent。重点检查：
- 提示词是否正确引用输入。
- 知识库是否检索到预期内容。
- 大模型是否在正确的条件下调用工具，工具入参和响应是否正确。
- 输出是否符合纯文本或结构化配置。
- 使用了当前用户数据时，是否已在调试设置中指定模拟用户。
至少测试正常输入、空值或边界输入，以及工具失败等异常情况。结构化输出还应检查字段是否缺失、类型是否稳定。
发布 Agent
Agent 修改会自动保存，但需要发布后才会在运行环境生效。更新预览 和 同步变更 都会发布最新的 Agent、行为流和 API 等后端配置；更新预览还会更新前端预览内容。
Agent 发布后会立即影响线上应用。修改输入、输出、模型、提示词或工具时，需要同时评估已发布页面、行为流和 Runtime API 调用是否仍然兼容。
使用 Agent
Agent 可以在页面、行为流或代码中使用。页面行为与行为流节点的配置入口不同，但创建会话、延续会话和使用结果的机制相同。
| 操作 | 用途 | 关键配置 |
|---|---|---|
| 开始会话 | 创建会话并执行 Agent | Agent、Agent 输入 |
| 继续会话 | 向已有会话发送新消息 | Agent、会话 ID、文本或多媒体内容 |
| 停止回复 | 停止当前正在生成的回复 | Agent、会话 ID |
| 删除会话 | 删除会话及其关联消息 | Agent、会话 ID |
- 页面或组件：在触发器中从 AI 菜单添加对应行为。行为支持 成功时 和 失败时 分支，也可以通过 请求时显示加载动画 控制等待期间的默认加载效果。
- 行为流：添加 AI 下的对应节点，并将 Agent 与数据库、API、条件和列表循环等节点组合。包含 AI 智能体节点的行为流必须使用异步执行模式，详见搭建行为流。
- Runtime API：通过代码创建会话、监听结果或管理消息，详见 Runtime API 参考 - AI 智能体。
一次性任务
对于总结、分类或生成单次内容等任务：
- 添加 开始会话 行为或节点。
- 选择 Agent，并将调用方的数据绑定到 Agent 输入。
- Agent 完成后，在后续行为或节点中使用返回结果。
- 根据调用位置配置错误提示、重试或其他异常处理。
纯文本输出的结果为文本；结构化输出可以按已配置的字段继续绑定。生成图片的模型应根据行为结果中实际返回的图片数据进行展示或保存。
多轮对话
多轮对话需要持续使用同一个会话 ID：
- 使用 开始会话 创建会话，并保存其行为结果中的会话 ID。
- 用户再次发送消息时，使用 继续会话，并传入保存的会话 ID。
- 需要中断正在生成的内容时，使用 停止回复。
- 不再保留会话时，使用 删除会话。
不要在继续会话时重新执行开始会话，否则会创建新的会话，之前的上下文不会延续。
在页面展示流式结果
开启流式输出后，在 开始会话 或 继续会话 中，将流式内容绑定到文本类型的页面变量，再由文本组件展示该变量。生成过程中变量会持续更新；需要保存或继续处理完整内容时，应在 成功时 分支中读取最终结果。
模型与 AI Point
Zion 提供多种系统模型，付费项目也可以使用自带模型（Bring Your Own Model，BYOM）。根据服务商和模型类型，BYOM 配置可能需要填写 API Key、服务地址、鉴权 Header 或模型标识，并在验证通过后保存和发布。
不同模型支持的输入、输出和工具能力不同，实际可用能力以编辑器中的模型标识和配置项为准。不要仅根据模型名称假设其支持图片、视频、结构化输出或工具调用。
模型调用和向量能力会消耗 AI Point。余额不足时，Agent 调用、数据向量化或向量搜索可能失败。可在项目详情中查看余额和消耗记录；项目版本包含的额度及加油包说明请参考管理项目资源。
运行数据
创建 Agent 后，系统会自动创建以下数据表：
| 数据表 | 记录内容 |
|---|---|
| 会话表 | 会话的发起用户、Agent 配置、模型、状态和错误信息 |
| 消息表 | 会话中的 system、user 和 assistant 消息 |
| 消息内容表 | 消息包含的文本、图片、视频、PDF、音频、JSON 或推理内容，以及 Token 使用量 |
| 工具使用记录表 | 工具名称、类型、请求、响应及其所属消息 |
这些表主要用于查询会话状态、展示历史消息和排查运行问题。系统表不能手动添加数据；调用开始会话、继续会话等操作时，系统会自动写入对应记录。
常见问题
- Agent 调试正常，实际调用却失败：依次检查 Agent 是否已经发布、调用方绑定的输入类型是否与当前配置一致、所选模型是否仍然可用，以及 AI Point 是否充足。使用工具时，还需要确认对应的行为流、API 或 Agent 已发布且调用参数有效。
- 结构化结果缺少字段或格式不稳定：为每个输出字段使用明确的英文名称和描述，并在系统提示词中说明所有必填字段及其含义。减少互相冲突的格式要求，并确认当前模型支持结构化输出。
- 模型已下架：使用已下架模型的 Agent 无法调试或发布，线上调用也会失败。收到编辑器通知后，应切换到可用模型，重新检查模型能力并完成调试和发布。
- 工具没有被调用或调用了错误的工具：检查工具名称和描述是否清楚说明调用时机，工具入参是否能从当前对话中获得，以及多个工具的职责是否重叠。工具是否被调用由大模型判断；必须执行的固定业务步骤应放入行为流，不应依赖 Agent 自主选择。