智能体、插件和实例的关系
本文说明智能体开发服务平台（AgentWorks）中模板、实例、插件和会话之间的关系，帮助你选对能力资源，弄清哪些资源会被共用，以及修改模板后会影响什么。具体术语的含义见术语表。
智能体模板与实例
每个智能体实例都由已配置的智能体模板创建。你在 智能体模板 中选择模型、编写提示词、设置工具权限和添加能力，再创建 智能体实例，让用户与助手对话。
例如，一份员工服务助手模板可以先创建测试实例，验证回答后，再创建正式服务实例：
模板保存可复用的模型、提示词、文件系统、Todo、压缩和插件等设置；实例使用这些设置处理请求、保存会话。同一模板可以创建一个或多个实例，各实例分别运行和管理。先做出一个可用实例即可，需要测试、面向不同用户或用于不同环境时，再创建更多实例。
渠道配置中的“应用实例”也指智能体实例。
复用智能体设计
员工服务助手验证通过后，可以保留这份模板，让后续实例沿用相同的回答规则和能力选择。需要改善回答时，先在独立的测试模板和实例中验证；验证通过后，再修改正式模板并更新关联实例。
修改智能体模板后，已有智能体实例需要手动更新；模板不会把修改立即推送给所有实例。具体方法见更新智能体模板并验证现有实例。
插件与能力资源
员工服务助手回答“差旅怎样报销”时，使用知识检索能力查找公司制度。能力、能力资源和插件配置各有不同作用：
- 能力：助手能检索公司制度并回答问题。
- 能力资源：知识库组提供可检索的资料范围；类似的资源还有 MCP 连接、记忆库、技能组和沙箱。
- 插件配置：智能体模板保存对知识库组的引用，创建出的智能体实例据此使用知识库组。
在智能体模板的 插件配置 中选择资源来源，保存后，可在详情页的 插件 页签核对资源名称和 ID。插件配置建立关联，实际提供数据、连接或工作区的是所关联的资源。
沙箱、MCP、知识库组和技能组可以选择模板或已有实例；记忆库在环境中已有可选记忆模板时，也可选择模板。其他插件的接法不同：平台工具包选择平台现成工具，用户工具包在模板中定义工具，由你自己的应用执行；子代理选择已有智能体实例。
共用或分别创建资源
这两种选择都记在智能体模板中，运行时使用的都是具体的能力实例。区别在于：创建智能体实例时，平台是否还要创建这项能力资源。
共用已有资源：所有助手都应检索同一份公司制度时，关联已有知识库组。智能体模板保存这个知识库组的引用；创建出的测试实例和正式服务实例都使用同一个知识库组，平台不再复制一份。
共用资料只需维护一份。修改共享知识库组时，测试实例和正式服务实例都会受到影响；如果要测试资料或检索设置的修改，请使用专用测试资源。
能力模板也适合重复使用固定配置。例如，每个助手都使用同一组 Skill 或相同沙箱规格，但分别拥有自己的技能组或沙箱。即使没有需要填写的参数，也可以按模板分别准备资源。
按模板分别生成资源：如果每个助手需要使用不同的业务系统账号，可以关联 MCP 模板，并把凭证字段设为可配置。平台创建智能体实例时，同时按 MCP 模板生成对应的 MCP 实例，并填入本次提供的凭证。
虚线表示模板保存的引用，实线表示创建实例或向智能体提供资料、连接。能力模板只保存准备方式，本身不会接收请求或执行工具。能力模板可以按需使用，与必须先配置的智能体模板不同。
MCP 模板开放了凭证参数时，实例创建者可以在控制台填写，也可以通过渠道 /init 提供；方法见为智能体实例按需生成 MCP 连接。其他能力不一定有这类可填写参数，例如知识库组的资料集合（Collection）和检索条数（top_k）在 /init 时直接沿用模板设置。各类差异见能力模板与实例的选择、关联与复用。
注意
分别创建实例后，还要检查实际使用的数据和账号
两个知识库组仍可以检索同一个 Collection，两个 MCP 实例也可以使用同一套凭证。需要分开个人数据或业务权限时，请核对实际关联的资料、记忆库、账号和工作区；不同资源 ID 本身不保证隔离。
能力模板的更新
只修改能力模板，不会自动改写已经生成的能力实例。下次根据这份模板创建能力实例时，会使用新的设置；已经生成的能力实例则需要重新应用配置。
要让已有智能体使用新设置，先保存引用这份能力模板的智能体模板，再编辑并保存目标智能体实例，最后重启智能体模板并验证实际调用。实例保存时，平台会按当前能力模板和实例参数重新写入生成资源的配置，通常保留原资源 ID。完整操作见应用新配置并验证。
注意
更新前保留生成资源上的手动修改
直接在生成的 MCP、知识库组、技能组或沙箱上改过的配置，可能被这次更新覆盖。需要长期保留的差异，请写入来源模板或已开放的实例参数。重启智能体模板会影响该模板下的多个实例；需要分阶段验证时，使用独立的测试模板和实例。
直接关联的已有能力实例不会被按模板重建；修改这种共享资源时，需要检查所有引用方。Skill 发布新版本或调整版本标记，还可能改变智能体读取的内容；这与技能组模板是否自动同步是两回事，参见Skill 版本对智能体的影响。
运行环境与沙箱
用户发送消息后，AgentWorks 使用智能体实例的配置调用模型、选择工具并组织回复。智能体实例可以直接完成问答，不需要先准备一台虚拟机。
员工服务助手查制度或调用业务系统时，是否需要沙箱取决于任务：
- 回答问题、检索知识、使用记忆库或读取 Skill：不必添加沙箱。Skill 提供做事方法和参考文件；读取后是否调用工具，由模型按任务决定。
- 调用业务工具：平台工具包在 AgentWorks 执行，MCP 工具在远程 MCP Server 执行，用户工具在你自己的应用中执行。这些工具不依赖 AgentWorks 沙箱。
- 需要 AgentWorks 提供执行环境：添加沙箱，用它运行脚本、命令或代码，使用特定依赖处理文件；访问沙箱中的对象存储挂载也需要添加沙箱。选择沙箱模板会为每个智能体实例准备沙箱；选择已有沙箱实例则共用工作区。
- 使用你自己的容器或执行服务：通过用户工具包或远程 MCP 工具执行，不必再添加 AgentWorks 沙箱。
沙箱的 Docker 容器或 Virtual Machine 选项说明执行环境的隔离类型。启动、回收和文件保留取决于沙箱规格与环境配置，不能据此把一个智能体实例当作一台长期保留的虚拟机。具体选择见配置沙箱模板和实例。
文件系统与工作区
智能体模板中的 文件系统 为模型提供 read_file、write_file 等文件工具。新建模板默认开启 启用文件系统；文件工具负责读写文件，运行命令则需要沙箱等执行环境。
使用 Skill 时，必须开启文件系统并保留 read_file，才能读取 SKILL.md 和参考文件。只需读取 Skill 和资料时，建议选择 仅只读，不必为此添加沙箱。既不使用 Skill，也不需要读写任务文件时，可以关闭文件系统功能。配置方法见将技能组添加到智能体模板。
工作文件存放在哪里，取决于沙箱选择：
| 沙箱选择 | 文件工具使用的位置 | 开始新会话后的文件 |
|---|---|---|
| 未关联沙箱 | 当前会话的文件空间 | 看不到上一会话创建的文件 |
| 关联沙箱模板 | 为这个智能体实例准备的沙箱工作区 | 仍使用同一工作区 |
| 关联已有沙箱实例 | 所选沙箱的共享工作区 | 仍使用同一工作区，其他使用者也可能修改文件 |
同一智能体实例的不同调用方共用它所关联的沙箱文件。不同智能体实例如果选择同一个已有沙箱，也共用其中的文件；新建会话不会将这些文件分开。
需要长期保留工作记录或文件时，把内容写入已批准的外部存储，并从存储端重新读取以确认。工具选择和存储方式见选择文件系统功能、沙箱和对象存储。
注意
共享沙箱只有一套挂载的 Skill 文件
智能体同时使用技能组和沙箱时，平台把所选 Skill 文件只读挂载到 /skills。多个智能体关联同一个已有沙箱时，后接入的智能体可能覆盖先前挂上的文件；需要不同 Skill 集合时，使用沙箱模板。
Skill 说明和沙箱挂载文件的版本需要分别验证。挂载文件不会自动执行，也不会自动安装依赖。
会话与共享资源
同一个员工服务助手可以处理多段会话。一段会话保留一段对话历史；每条输入触发一次运行，一次运行可以包含多次模型和工具调用。例如，先问报销规则、再补充出差地点，是同一会话中的两次运行；改聊假期问题时，可以开始新会话。
如果员工服务助手已关联记忆库和沙箱，不同会话会分别保留对话历史，但仍共用这些资源：
开始新会话后，助手使用新的对话上下文；已保存的记忆不会清空，关联的沙箱也不会重新创建。
在智能体模板中选择沙箱模板还是已有沙箱实例，决定使用哪个沙箱。新建 API 会话、渠道会话或调用任务，以及更换渠道用户或 API 调用方，都不会改变这项资源关系。每段会话或每次运行都需要全新环境时，见选择沙箱隔离范围。
运行结束与会话结束是两回事。当前输入处理完成后，可以在同一会话中继续提问。中断表示智能体正在等待审批决定或外部工具结果；先处理并回传，再继续等待这一轮结束，之后才能发送下一条输入。
Trace 可以查看输入、模型执行和工具调用，帮助检查助手做了什么。Todo 则是智能体整理当前任务的步骤清单；需要跨会话保存业务进度时，使用工单或工作流系统。API 会话和中断的操作见管理会话、运行和中断，飞书或 QQ 中的操作见管理渠道会话。
渠道账号与消息路由
渠道账号连接飞书、QQ 或 WebSocket 入口，保存渠道凭证和绑定方式。员工从飞书发送消息时，渠道账号决定消息交给哪个助手：
- 实例绑定：先创建一个员工服务助手实例，再把渠道账号绑定到这个实例。所有经该账号进入的消息都交给这个已有实例。
- 模板绑定：把渠道账号绑定到员工服务助手模板。飞书用户首次发送
/init时，AgentWorks 按模板创建该用户的专属实例，并保存用户绑定；后续消息按这个绑定发送给对应实例。
用户绑定记住“这位渠道用户使用哪个实例”，渠道会话则记住“当前继续哪段对话”。两者可以分别管理：开始新会话不会创建新智能体实例，删除用户绑定也不会删除原实例。
多位飞书用户使用同一个实例时，单聊仍分别保留对话历史；同一群聊则使用群聊上下文。分开对话历史不会自动分开记忆、沙箱或业务凭证，资源是否共用仍取决于插件配置。绑定方式见使用已有实例还是按用户创建，会话范围见管理渠道会话。
控制台与调用接口
在控制台创建和管理模板、实例、能力资源、渠道账号及 Token；让员工使用助手时，可以选择 网页版对话、飞书或 QQ，也可以让自己的业务应用通过 API 发送消息和接收回复。
调用 API 使用 WebSocket 渠道账号的 Token。这个 Token 用于调用绑定的智能体，不用于登录控制台或管理模板等资源。网页版对话的操作见测试智能体实例，业务应用可以通过 HTTP 和 WebSocket 调用智能体。
智能体调用接口
业务应用通过智能体调用接口（Bridge API）与助手对话：HTTP 提交消息、回传审批或工具结果，WebSocket 接收回复和运行事件。它们共同完成一次智能体调用，不是两套互相独立的接入方式。
这组接口不包含控制台内部的资源管理接口。名称含义参见术语表中的 Bridge API，接入流程参见API 接入概览。
问答与业务流程
AgentWorks 会处理每次输入：调用模型、执行或等待工具、返回结果。只有需要把多次调用与其他业务步骤按固定规则串起来时，才需要在自己的应用或工作流系统中增加外部编排。
直接使用智能体
员工在飞书问“去上海出差怎样报销”，助手检索制度并回答，就可以完成这次请求。网页版对话、QQ 和自己的业务应用也可以直接使用智能体实例；通过 API 接入本身不要求再搭建工作流。
在这种用法中，用户决定下一次问什么，AgentWorks 处理每次输入。只需完成问答或按需调用工具时，从这种方式开始即可。
接入业务流程
如果需要“收到报销申请 → 助手检查材料 → 系统确认材料齐全 → 提交审批”的固定顺序，就让业务应用保存申请进度，并在需要判断时调用智能体。助手处理当前任务，应用决定是否执行下一步。
应用用 HTTP 提交请求，用 WebSocket 收集回复和运行事件。遇到待审批或待执行工具时，先处理并回传结果，继续等原任务完成；失败、取消或还没收到最终结果时，保留当前步骤，不提交审批。只有运行成功且材料检查结果符合要求，才进入下一步。具体接入方法见确认结果后再执行下一步。
工作流中的条件分支、重试和进度由业务应用记录；智能体的 Todo 用来帮助完成当前任务，不能代替这份业务记录。
主智能体与子代理
员工服务助手也可以作为主智能体，把专业问题交给已有的制度检索助手或材料审核助手，再整合结果。主智能体和子代理都是智能体实例，名称说明它们在这次委托中的角色。
在主智能体模板中添加 子代理 时，关联的是已有实例，不会创建新实例。主智能体可以关联多个子代理，模型根据任务决定调用哪个；每次委托都会留下可检查的后台任务和结果。
如果业务要求固定调用顺序、条件分支、重试或终止条件，请在业务应用或工作流中设置这些规则；关联子代理本身不能保证按这些规则执行。配置见主智能体与子代理的关系，记录见检查子代理委托任务。