Appearance
应用服务
什么是应用
应用（App）是 AI 应用开发平台的核心概念，是 Agent 运行的载体。每个应用绑定一个 Agent 配置，包含模型选择、提示词编排、工具挂载、知识库关联等能力，对外以 app_id 作为唯一标识供 API 和渠道调用。
简单理解：应用 = Agent + 模型 + 提示词 + 工具/知识库等能力的组合封装。
一个应用从创建到可用经历以下阶段：
- 草稿阶段 — 在应用中心创建并编排应用配置（模型、提示词、工具等）
- 发布上线 — 将草稿发布为正式版本，生成语义版本号（如
1.0.1） - 渠道接入 — 通过 API、SDK、微信等渠道对外提供对话服务
应用类型
| 类型 | 标识 | 说明 |
|---|---|---|
| Agent | agent | 全功能 Agent，支持工具调用、沙盒执行、Skill、人工介入、Sub-agent 协作 |
| AgentLite | agent_lite | 轻量 Agent，支持工具调用与知识库，不支持沙盒与Skill |
| ChatFlow | chat_flow | 工作流驱动的对话应用，将对话逻辑编排为节点流 |
| 文本生成 | text_completion | 单次文本生成，无对话上下文，适用于文案撰写、摘要提取等 |
TIP
当前已开放创建的类型为 Agent、AgentLite、ChatFlow 和 文本生成。
Agent
Agent 是平台的核心应用类型，具备完整的智能体能力：
- 多轮对话 — 通过
conversation_id维持会话上下文，支持连续多轮交互 - 工具调用 — 可挂载插件工具、三方服务、内置工具、MCP 服务器、工作流等多种工具，Agent 自行判断何时调用哪个工具
- 知识库增强 — 关联知识库后，Agent 在回复时可检索知识库内容作为参考
- 沙盒执行 — 每次对话启动时自动创建独立沙盒环境，Agent 可在其中执行代码、操作文件、读写文档
- 技能加载 — 从技能中心挂载预置技能包，沙盒启动时自动同步技能文件，Agent 可读取技能文件并调用技能提供的工具
- 人工介入（HITL） — Agent 执行中可通过中断机制暂停，等待用户确认、输入或审批后恢复
- Sub-agent 协作 — 主 Agent 可动态派生 Sub-agent 处理子任务，支持多 Agent 协同工作
适用场景：医疗问答助手、报告分析 Agent、数据分析 Agent、审批流程 Agent 等需要复杂推理和工具配合的场景。
沙盒（Sandbox）
沙盒是 Agent 执行时的隔离运行环境，每次对话启动时自动创建，对话结束后关闭。沙盒为 Agent 提供以下能力：
代码执行
Agent 可在沙盒中执行 Python、Node.js、Bash 代码，并支持动态安装 pip/npm 依赖包。代码执行结果通过标准输出返回给 Agent，用于后续推理。
文件操作
Agent 可在沙盒的工作空间内进行完整的文件系统操作：
| 操作 | 说明 |
|---|---|
| 读取文件 | 读取指定文件的全部内容 |
| 按行读取 | 按行号范围读取文件内容，适合大文件部分查看 |
| 写入文件 | 将内容写入指定文件，文件不存在时自动创建 |
| 按行编辑 | 按行号范围替换文件内容，适合精确修改 |
| 列出目录 | 列出指定目录下的文件和子目录结构 |
| 搜索文件 | 按名称模式搜索工作空间中的文件 |
| 重命名/移动 | 重命名或移动文件和目录 |
| 复制 | 复制文件或目录到新位置 |
| 删除 | 删除文件或目录 |
文档处理
Agent 可在沙盒中读写常见办公文档格式：
| 操作 | 说明 |
|---|---|
| 读取 PDF | 提取 PDF 文件的文本内容 |
| 创建 PDF | 根据文本内容生成 PDF 文件 |
| 读取 Excel | 提取 Excel 文件的表格数据 |
| 写入 Excel | 将结构化数据写入 Excel 文件 |
| 读取 Word | 提取 Word 文件的文本内容 |
| 写入 Word | 根据文本内容生成 Word 文件 |
工作空间同步
沙盒启动后自动将应用关联的工作空间文件同步到沙盒内，确保 Agent 可以访问用户上传的文件和之前的操作产物。
沙盒生命周期事件
沙盒的创建、文件同步、技能加载过程通过 SSE 事件实时推送，客户端可据此展示进度状态：
| 事件 | 说明 |
|---|---|
sandbox.creating | 沙盒开始创建 |
sandbox.created | 沙盒创建成功，返回沙盒 ID |
sandbox.create_failed | 沙盒创建失败 |
sandbox.workspace_syncing | 工作空间文件开始同步 |
sandbox.workspace_synced | 工作空间文件同步完成 |
sandbox.workspace_sync_failed | 工作空间文件同步失败 |
sandbox.skill_loading | 技能文件开始加载 |
sandbox.skill_loaded | 技能文件加载完成 |
sandbox.skill_load_failed | 技能文件加载失败 |
技能（Skill）
技能是预置的能力包，从技能中心挂载到 Agent 应用后，在沙盒启动时自动同步到沙盒环境。Agent 可通过内置工具读取技能文件，获取技能提供的知识、脚本或配置，从而增强特定领域的能力。
技能分为两种来源：
| 来源 | 说明 |
|---|---|
| 官方技能 | 平台提供的预置技能，覆盖常见医疗场景 |
| 用户技能 | 用户自建或从技能广场导入的技能 |
技能也分为两种创建方式：
| 类型 | 说明 |
|---|---|
| 自定义创建 | 在平台内编写技能内容并发布 |
| 导入技能 | 从外部来源导入已有的技能包 |
技能支持版本管理，每个技能有独立的版本号（如 1.0.1），可在应用编排中选择指定版本。应用关联技能后，Agent 对话启动时技能文件会自动加载到沙盒，Agent 通过 get_skill_file 工具读取技能附带的文件内容。
AgentLite
AgentLite 是 Agent 的轻量版本，保留核心对话与工具调用能力，但不支持沙盒执行和技能加载：
- 多轮对话 — 与 Agent 相同的会话上下文管理
- 工具调用 — 可挂载插件工具、三方服务、内置工具（不含沙盒相关工具）、MCP 服务器、工作流等
- 知识库增强 — 关联知识库后，AgentLite 在回复时可检索知识库内容作为参考
- 提示词编排 — 支持系统提示词和变量输入
- 模型选择 — 支持 LLM 模型配置
WARNING
AgentLite 不支持沙盒执行（代码运行、文件操作、文档处理等）和技能加载。
适用场景：简单工具调用型对话（如查询三方 API、触发工作流）、知识库问答、FAQ 对话等不需要代码执行和文件操作的场景。
ChatFlow
ChatFlow 是工作流驱动的对话应用，将对话逻辑编排为可视化的节点流，按节点顺序执行并返回结果。
适用场景：需要固定流程的多步骤对话，如分步问诊、固定审批流程、信息采集表单等。
文本生成
文本生成是单次输入、单次输出的应用类型，无对话上下文：
- 提示词模板 — 定义输入变量和生成模板
- 单次输出 — 每次调用独立生成结果，不保留上下文
适用场景：文案撰写、摘要提取、翻译、报告格式化等一次性文本生成场景。
应用来源
| 来源 | 标识 | 说明 |
|---|---|---|
| 自建应用 | custom | 在平台内编排配置并发布的应用 |
| FastGPT 应用 | fastgpt | 对接 FastGPT 平台导入的应用 |
应用配置
一个应用的完整配置（AppSchema）包含以下能力模块：
模型配置
每个应用绑定一个 LLM 模型，指定模型 ID 和可选参数（Temperature、MaxTokens、TopP 等）。
开启 自由模式（loose_status）后，调用方可在请求中自由指定模型，而非强制使用应用预设模型。
提示词配置
应用使用系统提示词定义 Agent 的行为和角色，支持变量占位符 ，在对话时由用户输入替换。
提示词变量将数据结构与输入控件分开配置。数据结构可表示 String、Integer、Number、Boolean、Time、Object、Array 和 File；输入框、文本域、下拉选择器、多选选择器、日期选择器、代码编辑器和上传框等控件只决定输入方式，不改变变量值的数据类型。统一变量定义还包含显示名称、说明、是否必填、默认值、是否可写和是否加密等字段，具体场景可用项及完整协议见变量协议。
工具与能力
Agent 和 AgentLite 类应用可挂载以下工具与能力：
| 类型 | 说明 | Agent | AgentLite |
|---|---|---|---|
| 插件工具 | 自建或组件广场的 API 插件 | ✓ | ✓ |
| 三方服务 | 已接入的三方服务（如 Tavily 搜索、豆包语音等） | ✓ | ✓ |
| 内置工具 | 平台内置工具（网络搜索、时间、图像理解等） | ✓ | ✓ |
| 沙盒内置工具 | 文件操作、代码执行、文档处理等沙盒相关工具 | ✓ | — |
| MCP 服务器 | 通过 MCP 协议接入的外部工具服务器 | ✓ | ✓ |
| 知识库 | 关联知识库，增强回复准确性 | ✓ | ✓ |
| 技能（Skill） | 从技能中心安装的预置能力包 | ✓ | — |
INFO
文本生成类型不支持工具挂载。
Sub-agent 配置
Agent 类应用可配置 Sub-agent 协作：
| 配置项 | 说明 |
|---|---|
| 是否允许派生 | 启用后主 Agent 可动态派生 Sub-agent |
| 最大派生深度 | Sub-agent 的嵌套层级上限（默认 3） |
| 默认最大迭代轮数 | Sub-agent 单次执行的最大推理轮数 |
记忆配置
| 配置项 | 说明 |
|---|---|
| 短期记忆 | 控制上下文窗口轮数（默认 20 轮） |
| 长期记忆 | 关联记忆库，跨会话保留关键信息 |
交互配置
| 配置项 | 说明 |
|---|---|
| 开场白 | 用户进入对话时自动显示的欢迎语和建议问题 |
| 用户问题建议 | 启用后自动推荐相关问题 |
| 语音输入 | 语音转文字输入 |
| 语音输出 | 文字转语音播放 |
| 最大步数 | 单次对话的最大执行步骤数（默认 40） |
渠道接入
应用发布后，通过渠道（Channel）对外提供访问。平台支持以下渠道类型：
| 渠道类型 | 标识 | 说明 |
|---|---|---|
| API 访问 | api | 通过 OpenAPI 接口调用，适合自有系统集成 |
| SDK | sdk | 通过客户端 SDK 调用，适合 App/小程序嵌入 |
| 微信服务号 | wechat_service | 对接微信服务号，用户在微信内直接对话 |
| 微信公众号 | wechat_public | 对接微信公众号消息接口 |
| A2A | a2a | Agent-to-Agent 协议，供其他 Agent 调用 |
| 调试 | debug | 应用中心内部调试渠道 |
每个渠道绑定独立的鉴权凭证（API Key / Token），确保不同接入方的访问隔离。
版本管理
应用支持草稿与版本两级管理：
- 草稿 — 编辑中的未发布配置，可随时修改，不影响线上运行
- 已发布版本 — 发布后生成语义版本号（
x.y.z格式），线上渠道调用使用已发布版本
支持自动发版模式（is_auto_ver），草稿修改后自动发布为最新版本。
接口入口
应用服务相关的 API 接口文档：
应用管理
会话与消息
Agent
- Agent - 发送消息 — Agent 对话接口，支持 chat 与 resume 模式
- Agent - 停止响应 — 中止 Agent 当前任务的 SSE 流
- Agent - 文件操作 — Agent 工作空间文件管理接口
AgentLite
- AgentLite - 发送消息 — AgentLite 对话接口，支持 chat 与 resume 模式
- AgentLite - 停止响应 — 中止 AgentLite 当前任务的 SSE 流
ChatFlow
- ChatFlow - 发送消息 — ChatFlow 对话接口，支持工作流事件与中断恢复
- ChatFlow - 停止响应 — 中止 ChatFlow 当前任务
TextCompletion
- TextCompletion - 文本生成 — 单次文本生成接口，无对话上下文
- TextCompletion - 停止生成 — 中止 TextCompletion 当前任务的 SSE 流