智能体、插件和实例的关系
一体化智能体运行与协同平台（AgentWorks）的对象可以分成设计、能力关联、运行和接入四层。先按任务使用产品，需要复用或治理时再理解插件、模板和实例之间的关系。
区分智能体模板和智能体实例
智能体模板保存可以复用的设计，智能体实例承载实际运行和接入。
| 文档概念 | 控制台标签 | 作用 |
|---|---|---|
| 智能体模板 | 智能体模板 | 保存可复用模型、提示词、模板级审批处理规则和插件配置 |
| 智能体实例 | 智能体实例 | 实际运行、保存会话并被 API 或渠道调用 |
“智能体”在任务标题和概括性说明中泛指要构建的智能体。涉及创建、选择、编辑或更新具体资源时，“智能体模板”表示可复用设计，“智能体实例”表示运行对象。
一个智能体模板可以创建多个智能体实例。修改智能体模板后，已有智能体实例需要手动更新。
渠道账号的部分配置界面使用“应用实例”指代智能体实例。两者指同一种由智能体模板创建的运行实例。
区分能力、插件和能力资源
能力描述智能体可以做什么，能力资源提供实际数据或运行环境，插件配置负责建立关联。
| 概念 | 作用 | 示例 |
|---|---|---|
| 能力 | 描述智能体可以完成的事情 | 检索知识、调用工具、保存记忆或执行命令 |
| 插件配置 | 保存智能体模板与能力对象之间的关联 | MCP - 实例、沙箱 - 模板、平台工具包或子代理 |
| 能力资源 | 提供实际连接、数据、内容或运行环境 | MCP 连接、知识库组、记忆库、技能组或沙箱 |
要让智能体使用某项能力，请先创建对应的能力资源，再到智能体模板的 插件配置 中选择对应的能力资源。保存后，可以在智能体模板详情页的 插件 页签中核对关联的类型、名称和资源 ID。
对于沙箱、MCP、知识库组、记忆库和技能组，插件配置还要指定模板或实例。其他插件使用不同方式：平台工具包选择平台提供的现成工具，用户工具包在智能体模板中定义工具契约，子代理选择已有智能体实例。它们不使用同一套模板和实例选择。
区分能力模板和能力实例
能力模板保存可重复使用的配置，并决定创建智能体实例时可以填写哪些参数。插件选择模板后，平台在创建智能体实例时按照模板准备或绑定运行所需资源。
插件选择实例时，智能体模板直接关联已经存在的能力资源，例如：
- 一个 MCP Server 连接。
- 一个知识库组。
- 一个记忆库。
- 一个技能组。
- 一个沙箱资源。
模板不是必须的中间层。只有需要重复使用配置、开放实例参数或按统一基线准备资源时才使用；单一固定资源可以直接通过实例选项关联。能力模板可能为智能体实例准备独立资源，也可能关联共享资源；具体关系参见模板和实例如何影响资源。
技能组和沙箱展示了不同的资源行为：技能组确定 Skill 组合和版本，运行时按需激活 Skill、读取相关资源；沙箱模板为智能体实例准备执行环境。来源智能体模板同时关联两者时，Skill 文件不会自动进入沙箱。任务需要执行代码时，还应通过沙箱自身的工具、文件和依赖完成执行。
理解渠道账号和用户绑定
- 渠道账号：连接飞书、QQ 或 WebSocket 入口，保存渠道凭证和绑定模式。
- 实例绑定：渠道账号把消息发送到一个已有智能体实例。
- 模板绑定：渠道用户发送
/init，平台动态创建智能体实例。 - 用户绑定：记录渠道用户与动态创建智能体实例的关系。
- 渠道会话：记录消息上下文，不等于智能体实例。
理解会话、调用任务、记忆库和沙箱
这些对象分别管理对话上下文、单次运行、跨会话信息和隔离执行环境。
| 概念 | 回答的问题 | 生命周期 |
|---|---|---|
| API 会话 | 哪些 API 请求属于同一段多轮对话？ | 首次请求不发送 session_id，平台返回新 ID；后续复用该 ID 继续对话 |
| 渠道会话 | 渠道用户当前在哪一段对话中？ | 平台按渠道账号、用户或群聊选择上下文；渠道用户不需要填写 session_id |
| 调用任务 | 平台正在处理哪一次输入或中断响应？ | 每次输入启动一次运行；completed 或 error 结束本次运行，interrupted 表示暂停等待响应 |
| 记忆库 | 哪些信息可以在另一段会话中继续检索？ | 独立于会话管理；新建会话不会创建或清空记忆库 |
| 沙箱 | 智能体在哪里执行已配置的命令或文件工具？ | 由智能体的插件配置和资源关系决定，不会因为新建会话而自动创建 |
同一 API 会话只能有一个活动调用任务流。调用任务完成、失败、暂停或状态不可查询，不表示整个会话、记忆库或沙箱同时结束。
Trace 用于检查一次或多次运行的输入、模型执行和工具调用。API 会话的完整处理方式参见管理 API 会话、调用任务和中断；渠道会话参见管理渠道会话。
区分控制台管理和对外调用
控制台用于管理智能体模板、智能体实例、能力模板、能力实例、渠道账号和 Token。
可以通过以下方式使用智能体实例：
- Invoke API（控制台中的 API 调用）。
- WebSocket 接入。
- 飞书和 QQ 消息。
- Playground。
临时调试 Token 和 Agent API Token 只用于 API 调用，不能代替控制台登录态管理对象。
区分平台单次运行和可选的外部编排
无论通过 Playground、飞书、QQ、Invoke API 还是 WebSocket 使用智能体实例，一体化智能体运行与协同平台（AgentWorks）都会执行一次平台托管运行。外部编排不是必经层；只有调用方需要在多次调用或多个业务步骤之间固定控制流程时，才需要增加外部编排。
| 使用方式 | 是否需要外部编排 | 跨调用流程由谁控制 | 常见入口 |
|---|---|---|---|
| 直接使用智能体实例 | 不需要 | 用户或业务应用发起每次交互；AgentWorks 处理每次平台运行 | Playground、飞书、QQ、直接 Invoke API 或 WebSocket |
| 在外部流程中调用智能体实例 | 可选，仅在需要固定流程控制时使用 | 业务应用、工作流系统或智能体框架 | 通常使用 Invoke API |
直接使用智能体实例
飞书、QQ 和 Playground 等入口可以把用户输入直接交给智能体实例。业务应用或自有消息系统也可以通过 Invoke API 或 WebSocket 直接发送输入并取得结果，而不在两次调用之间维护固定的流程状态。
业务场景本身不等于外部编排。例如，飞书中的问答助手可以服务于业务任务，但如果没有外部系统保存流程状态并决定下一步，就不存在外部编排。使用 Invoke API 或 WebSocket 也不自动形成外部编排；它们是接入接口，不是工作流状态模型。
在外部流程中调用智能体实例
需要固定控制节点顺序、条件分支、并行、重试或终止条件时，由外部业务流程或智能体框架保存状态并选择下一步。AgentWorks 智能体实例在这种组合中提供一次受平台治理的智能体运行。
外部流程通常通过 Invoke API 调用智能体实例，并负责流程状态、重试、终止、业务副作用以及流程执行与 session_id 的对应关系。自有消息系统可以使用 WebSocket，但不应使用 WebSocket 代替流程状态管理。AgentWorks 提供通用调用接口，不提供 LangGraph、ADK 或 CrewAI 的专用适配器。
子代理让模型把任务动态委托给已有智能体实例，但不提供固定节点、路由、重试或终止条件。需要精确控制这些步骤时，由外部系统保存编排状态并调用相应智能体实例。参见理解模型驱动的动态委托和选择目标部署提供的集成接口。
何时使用模板和实例
需要复用配置或创建多个运行对象时，先保存智能体模板，再根据使用环境或渠道用户创建智能体实例。模板和实例模式支持：
- 一个智能体模板创建多个受控智能体实例。
- 动态渠道用户获得专属实例。
- 复用经过验证的能力配置。
- 在实例级管理 Token、渠道、状态和 Trace。
- 让平台管理员限制租户可新增的能力类型。