常见问题
本页按智能体开发服务平台（AgentWorks）的使用过程整理常见问题。第一次使用时，从开始使用与能力范围开始；需要评估运行环境、隔离和文件保留时，查看运行环境、隔离与文件保留；如果你熟悉 LangGraph、CrewAI、AgentCore、AgentKit、Copilot Studio、Gemini 或 A2A 等平台、框架和协议，可以直接查看兼容性与迁移。
开始使用与能力范围
我是云平台超级管理员，为什么在 AgentWorks 中仍然没有权限？
云平台的“超级管理员”身份不会自动带来 AgentWorks 权限。请让已具备 AgentWorks 授权权限的管理员，为你的账号或所属用户组分配相应策略；如果团队还没有可以授权的管理员，请联系平台提供方确认初始授权。
能否不准备沙箱、MCP、记忆库、知识库和 Skill，直接创建智能体模板？
可以。第一个智能体只需要可用的模型凭证、模型和系统提示词。创建后再创建智能体实例，通过 网页版对话 验证。
AgentWorks 更适合通过控制台配置，还是通过代码定义？
AgentWorks 的智能体构建路径以控制台配置为主：创建智能体模板，选择模型凭证和模型，填写系统提示词并按需添加能力，再创建智能体实例。智能体调用 API 用于调用已有智能体实例，不用于上传编排代码或定义智能体运行图。
已有业务系统或编排程序可以继续在 AgentWorks 外部运行，并通过 API 调用智能体实例，或者通过 MCP 和用户工具包向智能体提供工具。参见创建第一个智能体并完成基础验证和通过 API 接入智能体。
能否不创建智能体模板，直接创建第一个智能体实例？
不能。每个智能体实例都必须引用一个已经存在的智能体模板。实例创建页面只允许选择已有模板，不会自动创建模板。
这不表示必须提前准备能力模板。模型凭证、模型和系统提示词足以创建第一个智能体模板；随后即可用它创建智能体实例。模板绑定渠道中的 /init 也只自动创建实例，渠道账号仍需预先绑定智能体模板。
智能体模板和智能体实例分别用于什么？
智能体模板保存可复用设计；智能体实例是 网页版对话、API 和渠道实际调用的运行入口。新建实例可以先保持 待启动，平台在首次调用时按需启动。同一模板可以创建多个实例，分别用于开发、预发布、生产或不同渠道用户。
如果你熟悉其他平台中的 agent blueprint、configuration 或 deployment/runtime，可以把智能体模板理解为可复用设计，把智能体实例理解为实际运行对象；它们并不等同于一次会话或一个线程。参见智能体、插件和实例的关系和开始使用智能体实例。
运行环境、隔离与文件保留
本节用于判断何时需要沙箱、哪些对象共享沙箱，以及哪些运行和保留规则需要在上线前确认。
AgentWorks 是否为每个智能体、用户或会话常驻一台虚拟机？
不是。智能体模板、智能体实例、用户、会话和调用任务都不与一台专属虚拟机一一对应。AgentWorks 会运行智能体实例，但只有智能体模板配置了沙箱能力时，智能体才会获得可用于运行命令和处理文件的沙箱。创建会话或调用任务不会自动创建沙箱。
选择 沙箱 - 模板 时，每个新建智能体实例会获得一个沙箱；选择 沙箱 - 实例 时，多个智能体实例可以复用同一个现有沙箱。沙箱可以使用 Docker 容器或 Virtual Machine；隔离类型不表示沙箱一定常驻，也不决定空闲回收方式。参见选择沙箱模板或实例。
能否只开放显式工具，不向智能体提供命令执行环境？
可以。“平台工具包”不是沙箱工具列表，而是 AgentWorks 内置工具的选择入口。添加平台工具包不会创建或关联沙箱。即使没有配置沙箱，智能体仍可使用平台工具包，以及 MCP、用户工具包、知识库、记忆库和 Skill。
MCP 工具由远程 MCP Server 执行，用户工具由接入方业务系统执行，也不需要 AgentWorks 沙箱。只有需要沙箱提供的命令、文件或代码执行工具时，才添加沙箱。无论采用哪种方式，工具服务和业务系统仍需使用自己的身份、权限和允许范围控制操作。参见Skill、平台工具包、用户工具包和 MCP 有什么区别？和工具审批规则能代替工具服务的访问授权吗？。
新建智能体为什么已经有文件工具？
新建智能体模板默认开启文件系统功能，因此即使没有添加沙箱，也可能获得 read_file、write_file 等智能体文件工具。既不使用 Skill，也不需要读写任务文件时，可以关闭 启用文件系统。使用 Skill 时必须开启并保留 read_file；只需读取时建议选择 仅只读。清空工具选择表示采用运行时默认工具集，不等于关闭文件系统。
未关联沙箱时，智能体文件工具按会话读写文件，新会话看不到上一会话创建的文件。关联沙箱后，这些工具改为使用所关联沙箱的工作区：沙箱模板为每个智能体实例创建沙箱，现有沙箱实例则由关联它的智能体共享。需要长期保留文件时，请写入已批准的外部存储。未配置文件系统的模板按关闭处理。参见了解文件系统功能和工作文件和选择文件系统功能、沙箱和对象存储。
开启“启用文件系统”后，文件保留在哪里？
在 文件系统 中开启 启用文件系统 后，模型可以使用智能体文件工具。未关联沙箱时，这些工具按会话读写文件，新会话看不到上一会话创建的文件。关联沙箱后，文件工具改为读写所关联沙箱的工作区。
未关联沙箱时，这类文件适合保存一次会话中的任务中间结果。需要跨会话或运行环境回收保留结果时，请写入已批准的外部存储，并从存储端重新读取以确认内容。
使用 OSS 挂载前必须开启“启用文件系统”吗？
不需要。启用文件系统 控制 read_file、write_file 等智能体文件工具；OSS 挂载来自沙箱模板或沙箱实例中的 存储挂载 配置，两者独立。
访问 OSS 挂载必须把相应沙箱接入智能体，但不必为此开启文件系统功能。关闭文件系统后，沙箱命令工具仍可按运行环境权限读取或写入沙箱本地文件；访问 OSS 挂载路径时，还受该挂载的读写设置约束。参见挂载对象存储。
关闭文件系统后，为什么沙箱里仍可能出现本地文件？
智能体文件工具和沙箱命令工具是两条独立路径。关闭 启用文件系统 后，模型不再使用 read_file、write_file 等智能体文件工具；沙箱命令仍可按运行环境权限创建本地文件。
要区分沙箱本地文件和对象存储中的对象，请先确认命令使用的是挂载配置中的本地目录。写入后，再从对象存储控制台或组织批准的客户端按完整对象路径读取并核对内容。同一沙箱能够立即读回，只能说明当前工具可以读取该路径，不能代替对象存储端核验。参见挂载对象存储。
“沙箱模板启动类型”选择什么？
该标签选择沙箱隔离类型，即 Docker 容器或 Virtual Machine。冷启动或预热策略由平台管理员在沙箱规格中配置。
沙箱会自动休眠或回收吗？空闲期间如何计费？
沙箱在第一次工具调用时创建或分配运行环境。同一沙箱资源 ID 的运行环境仍可用时，后续工具调用可能继续使用该环境。沙箱隔离按资源划分，而不是按 AgentWorks 会话或调用任务划分；需要隔离文件、进程或凭证时，请使用不同的沙箱资源。
对于 Docker 沙箱，运行环境销毁时会自动移除容器，容器内部可写层中的文件随之消失。外部工作目录和对象存储挂载会被卸载，外部文件或对象继续由对应存储的保留和删除规则管理。
上线前，请让平台管理员确认所选规格实际生效的启动方式、单次运行超时、空闲回收时间、文件保留和计费方式；空闲期间的费用以目标环境的计费说明或服务合同为准。
长任务还应在应用层设置截止时间、取消处理和幂等恢复。规格页面中的数值仅供配置参考，Docker 容器或 Virtual Machine 只表示隔离类型。参见上线前确认启动、回收、保留和费用和限制沙箱网络和资源。
是否支持会话级、线程级、任务级或单次运行级沙箱隔离？
创建新会话、开始新的调用任务、更换渠道用户或 API 调用方，以及取消运行，都不会自动创建、切换或清空沙箱。
选择 沙箱 - 模板 时，每个新建智能体实例会获得一个沙箱实例；选择 沙箱 - 实例 时，多个智能体实例可以复用同一个现有沙箱。需要按用户分别使用沙箱资源时，应准备不同智能体实例并选择沙箱模板。
如果通过 HTTP API 和 WebSocket 事件接入，并且每段会话或每次运行都要求全新执行环境，可以通过用户工具包在调用方管理的外部环境中执行工具；该环境不是 AgentWorks 沙箱。如果工具必须在 AgentWorks 沙箱内运行，只能在请求流程之外分别准备智能体实例和沙箱资源，不能通过 Agent API 动态完成。参见选择沙箱模板或实例、选择沙箱隔离范围和按会话或调用任务管理外部执行环境。
会话、记忆、工作文件和沙箱文件分别会保留多久？
没有适用于这些状态的统一保留时长。它们具有不同的生命周期：
- 会话和历史消息的保留取决于目标环境配置。停止使用会话、取消运行或进行上下文压缩，都不等于删除留存数据。
- 记忆库存储独立于会话。开始新会话不会创建或清空记忆库；多个智能体实例是否共享记忆，取决于它们关联的记忆库实例。
- 文件系统功能提供智能体文件工具。未关联沙箱时，这些工具按会话读写文件，新会话看不到上一会话创建的文件；需要跨会话长期保留时，请写入已批准的外部存储。
- 沙箱文件和进程属于相应沙箱实例。复用同一个沙箱的智能体会共享其工作区；Docker 容器内部可写层中的文件在运行环境销毁时消失，外部工作目录能否继续保留则取决于管理员提供的环境。
- 对象存储挂载连接企业自有存储；沙箱实例释放后，AgentWorks 不删除其中的对象。对象自身的保留、版本和删除规则由存储所有者管理。
需要长期保留的文件和结果应写入管理员确认受支持的外部存储，不要把沙箱工作目录作为唯一副本。参见API 会话会自动过期或删除吗？和准备沙箱执行内容。
凭证是否会进入沙箱？
不一定，取决于凭证的提供方式。用户工具包的业务代码和凭证由接入的业务系统管理；MCP Server 也可以在沙箱外完成授权。把凭证作为沙箱环境变量、文件或其他运行输入提供时，该凭证会进入沙箱的使用范围。不要在提示词、Skill 文件或命令参数中传递原始凭证。
多个智能体复用现有沙箱实例时，它们会使用相同的环境变量、对象存储挂载和凭证，这些内容不会按智能体或会话自动隔离。优先通过用户工具包或在沙箱外完成授权的 MCP 服务处理最终用户凭证；确需向沙箱提供凭证时，使用最小权限和最短有效期，并避免共享给无关智能体。一个沙箱表单中的全部对象存储挂载也共用同一对象存储凭证。参见准备沙箱执行内容、挂载对象存储和保护凭证和 Token。
创建实例与接入
什么时候直接创建一个智能体实例？
需要让控制台测试、API 调用或渠道绑定长期使用同一个固定实例时，直接创建智能体实例。例如，生产客服机器人或后端服务集成可以各使用一个实例。
如果每个渠道用户需要专属智能体实例，可以使用模板绑定和 /init 动态创建。
平台支持批量创建智能体实例吗？
控制台一次只能手动创建一个智能体实例；使用模板绑定的渠道用户还可以在首次发送 /init 时动态创建专属实例。
渠道应该绑定已有实例，还是按用户创建实例？
请先确定只需分开对话，还是还要分开管理智能体实例及其资源，再选择绑定方式：
- 用户使用相同配置和能力，只需分开对话：绑定已有智能体实例，并使用不同渠道会话。
- 需要分别管理实例参数、沙箱或生命周期：绑定智能体模板，让用户发送
/init按需创建实例；需要分别保存记忆时，还必须为各实例准备独立记忆库。
企业 FAQ、制度问答和公共服务台通常可以共享一个智能体实例。个人工作助手、客户专属助手、培训教练或研发运维助手更适合按用户开通。
按用户开通会创建不同的智能体实例，但不会自动拆分记忆、数据或权限。如果多个实例连接同一个记忆库、MCP 凭证或业务系统账号，这些资源仍然共享。参见了解绑定模式：使用已有实例还是按用户创建和构建按用户开通的飞书个人工作助手。
修改智能体模板后，智能体实例会自动更新吗？
不会。列表会提示 智能体模板更新，实例需手动更新。编辑并保存实例后，再验证回复、工具调用和 Trace。更新还会重新应用能力模板及实例参数，可能覆盖对自动生成的能力实例所做的单独修改；直接关联的已有能力实例不属于这一生成流程。更新前先记录需要保留的配置，参见更新智能体模板和实例。
会话会保留什么？创建新会话会清空记忆库吗？
会话保存多轮对话的上下文。WebSocket 事件帧中的 sid 对应会话 context_key，mid 对应该次输入的 msg_id，不要将它们混用。未关联沙箱时，工作文件也按会话使用；需要跨会话或重启后继续使用的文件，请写入已批准的外部存储。
开始新会话不会创建或清空记忆库、沙箱或对象存储挂载。调用方应保存用户、业务对话和返回会话标识的对应关系，不要在不同用户之间复用。参见管理会话和中断和验证记忆范围。
会话何时创建，什么时候算结束？
平台按请求中的 user_id、chat_type 和 chat_id 处理消息；本文使用的 group 模式在 HTTP 响应中返回 context_key 和 msg_id，分别对应事件帧的 sid 和 mid。一次消息处理成功、失败或取消，不等于整个会话或其中的历史已被删除。
网页对话可以通过 开启新对话 开始另一段对话；支持会话指令的渠道可以使用 /session new、/session list、/session use 和 /session clear。参见管理会话和中断和管理渠道会话。
能否像旧 Invoke 一样，通过调用接口直接提交文件？
不支持。当前智能体调用 API 中，SendMessage 只接收文本，不接受旧 Invoke 的 files 数组或 Base64 文件附件。
如果任务需要处理文件，可通过已配置的知识库、沙箱、MCP 服务或用户工具包准备和读取文件；这些方式不等于通过消息接口直接上传附件。
API 会话会自动过期或删除吗？
不要依赖空闲等待来获得新的对话上下文。业务应用应根据用户、主题、权限范围以及最大时长或轮数规则，主动决定何时开始新会话。历史查询是否启用、能查多久，以及数据的清理规则，由目标环境的配置决定。
停止使用一个会话不表示历史已经删除。组织要求按期限清理历史时，上线前与平台管理员确认数据保留和清理流程。上下文压缩也不是过期或删除功能。参见规划会话边界、上下文和数据保留。
运行结束或取消后，会话历史会被删除吗？
不会。运行事件中的 success、error 和 cancelled 终止阶段描述本次运行，不代表会话历史、记忆或沙箱文件已删除。在支持会话指令的渠道中，清空当前会话上下文使用 /session clear；需要清理留存数据时，另按组织的数据保留流程处理。
可以由业务事件自动调用智能体吗？
可以。外部业务系统可以在事件发生时调用已有智能体实例：通过 HTTP 接口提交消息，并订阅 WebSocket 事件取得结果。飞书和 QQ 渠道则由用户消息触发。
接入时，请在外部系统中完成事件订阅、身份校验、渠道身份、会话与业务用户的对应关系、流程状态、超时、重试、幂等和终止判断。需要处理人工审批或流式响应时，参见处理多个待审批调用和判断流式运行是否完成。接入方式的完整选择方法见选择智能体的使用方式。
扩展智能体能力
插件和沙箱、MCP、记忆库等资源是什么关系？
请先在沙箱、MCP、记忆库、知识库组或技能组管理页面创建能力资源，再在智能体模板的 插件配置 中选择所需资源。创建或更新智能体实例后，智能体才能在运行中使用相应能力。
对于提供模板和实例选项的插件：
- 选择模板，表示创建智能体实例时按照模板准备或绑定所需资源。
- 选择实例，表示直接连接一个已经存在的资源。
保存智能体模板后，可以在智能体模板详情页的 插件 页签中核对关联。随后仍需创建或更新智能体实例，并通过测试和 Trace 确认能力实际生效。
Todo 适合处理什么任务？开始新会话后还会继续吗？
Todo 用来帮助智能体在当前任务中列出、更新和完成步骤，例如“收集资料、生成报告、检查结果”。开始新会话后，智能体不会自动接着原清单处理；没有新的调用时，Todo 也不会自行在后台推进后续步骤。
如果需要在新会话中继续使用原有进度，或需要系统根据任务状态自动推进后续步骤，请把任务记录保存在组织使用的工单、工作流或业务系统中。参见创建智能体模板。
Skill、平台工具包、用户工具包和 MCP 有什么区别？
- Skill：包含
SKILL.md和相关文件的版本化内容包，为智能体提供任务说明、方法和资源；它本身不等于一个托管工具服务。 - 平台工具包：AgentWorks 内置工具的选择入口，不是沙箱工具列表。AgentWorks 执行所选工具包中的操作；用户从控制台可见的工具包列表中选择。
- 用户工具包：用户在智能体模板中定义工具名称和输入输出结构；通过 HTTP API 和 WebSocket 事件接入的业务系统接收中断、执行工具并返回结果。
- MCP：工具由 AgentWorks 外部的 MCP Server 提供，平台通过 Streamable HTTP 发现并调用。
参见创建和维护可复用的 Skill、使用平台工具包、使用用户工具包和选择 MCP 实例或模板。
Trace 中的 Skill 工具是什么？需要手动调用吗？
不需要手动调用。关联技能组后，智能体根据任务选择 Skill，再通过 read_file 读取对应的 SKILL.md 和相关资源。因此，智能体模板还必须开启文件系统并保留 read_file；只需读取时建议选择 仅只读。
在 Trace 中核对 read_file 的目标路径和返回内容。它也能读取普通文件，因此不能仅凭出现这个调用就判断 Skill 已经加载。
读取 Skill 内容不等于运行命令、安装依赖或执行外部操作。还要分别核对智能体读取的说明和沙箱中可见的文件，不能仅凭技能组选定版本就断定两者一致，参见验证运行中的 Skill 版本。
具体配置参见将技能组添加到智能体模板，读取方式参见让智能体按需激活 Skill和读取 Skill 引用的资源。
为什么配置了“工具权限”后，工具仍然直接执行？
先确认智能体模板中的 工具权限 不是空配置。添加允许或拒绝规则、设置默认行为，或者开启 生成审批描述，都会让工具权限参与处理；这些配置都为空时，工具会直接执行。要让没有命中规则的调用进入人工审批（HITL），请将默认行为设为 审批。
还要检查调用是否属于始终自动通过的内置工具，例如文件系统功能提供的只读工具、Todo、压缩、部分子代理和记忆工具。这些工具不进入人工审批。沙箱、MCP 和其他可审批工具统一使用智能体级工具权限。参见理解规则顺序和默认行为和了解不会进入人工审批的内置工具。
渠道用户的工具审批规则会覆盖模板规则吗？
不会。对于已经建立用户绑定的渠道调用，平台先检查智能体模板中的拒绝和允许规则；模板规则一旦命中，就不会继续检查渠道用户规则。只有模板规则未命中时，才检查对应 用户绑定 中的 工具权限规则。
需要按用户区分自动批准范围时，让目标调用在模板中保持需人工处理，再配置用户补充规则。渠道用户规则只会自动批准全部匹配允许规则的调用；拒绝或未命中不会直接拒绝工具，而是继续人工审批。必须自动拒绝的范围应放在智能体模板拒绝规则中。不要使用会提前匹配所有用户的宽泛模板允许规则。参见根据接入方式处理人工审批。
工具审批规则能代替工具服务的访问授权吗？
不能。工具权限决定调用是自动批准、自动拒绝还是交由人工处理；工具服务、MCP Server、沙箱或业务系统仍会使用自己的身份和权限执行请求。
必须禁止的操作应同时使用最小权限凭证、服务端授权、调用方允许列表或沙箱网络策略限制。不要把模板拒绝规则当作唯一的安全边界。
“工具权限”中的工具名称、参数名和匹配正则从哪里找？
工具名称来自工具的可调用名称，参数名来自输入 schema 顶层 properties，匹配正则则由你根据允许或限制的参数值编写。MCP 工具可以在 MCP 实例的 工具列表 中查看名称和输入 schema；沙箱工具列表提供名称和描述，需要按参数值配置时先通过低风险测试和 Trace 核对参数。
名称必须与工具定义完全一致。参数名和匹配正则必须同时填写；任一项留空时，规则只按工具名称生效。无法确认参数结构时，应保留人工审批，不要猜测参数名或创建宽泛允许规则。参见找到工具名称和参数名。
Skill 中的文件和脚本在哪里使用？添加 Skill 后会自动执行吗？
智能体通过技能组选择 Skill，再用 read_file 读取说明和相关资源。使用前必须在智能体模板中开启文件系统并保留 read_file；只需读取时建议选择 仅只读，不必为此添加沙箱。读取脚本文件只会取得其内容，不会自动执行、安装依赖或注册工具。
同一个智能体模板同时使用技能组和沙箱时，所选 Skill 文件会只读挂载到沙箱的 /skills 目录。使用已有 沙箱 - 实例 时，挂载仍写到那个共享沙箱的同一个 /skills。两种方式都不会自动执行脚本或安装依赖。
注意
共享沙箱的 Skill 文件可能被覆盖
后接入的智能体可能覆盖 /skills 中先前挂上的文件。需要不同 Skill 集合时，改用沙箱模板。
创建或更新智能体实例后，应分别确认 Skill 激活、实际文件路径和沙箱执行结果。参见为 Skill 配置执行能力和准备沙箱执行内容。
多个智能体可以共享一个沙箱实例并分别使用不同 Skill 吗？
不支持。共享沙箱只有一个 /skills 视图，不会按智能体合并或切换 Skill 文件。智能体 A 使用 Skill 1–3 并先初始化共享沙箱后，智能体 B 即使配置了 Skill 4–6，也可能仍只看到 Skill 1–3。
需要不同 Skill 集合时，请为每个智能体选择 沙箱 - 模板。只有所有引用方有意共享相同文件、Skill 集合和执行状态时，才复用现有沙箱实例。
用户工具包中的工具在哪里运行？沙箱或子代理可以执行吗？
用户工具由通过 HTTP 与 WebSocket 调用智能体的应用处理。你的应用接收工具中断，可以运行自己的代码，也可以调用自己管理的沙箱或其他执行服务，再返回结果。
AgentWorks 沙箱不会因为与用户工具包同时添加到一个智能体模板而自动成为它的执行器，主智能体也不会代替你的应用处理子代理运行中的用户工具中断。
参见使用用户工具包、配置沙箱模板和实例和准备并独立验证目标实例。
可以让智能体使用我自己的沙箱吗？
可以通过用户工具包接入：你的应用接收工具中断，在自己管理的沙箱中执行操作，再返回结果。需要在应用中实现工具处理、环境选择和清理，具体方式参见在自己的沙箱中执行代码和处理文件。
子代理是否等同于多智能体工作流？
不等同。子代理把任务异步委托给已有智能体实例，并提供任务状态和结果；控制台不提供任意工作流图编辑。
如果你熟悉 crew、connected agent 或 subgraph，可以把子代理理解为受管理的实例间任务委托，而不是嵌套工作流。需要精确控制流程时，由外部编排系统调用相应智能体实例。参见理解模型驱动的动态委托。
主智能体如何知道子代理任务已经完成？
每次子代理委托都有一条后台任务。主智能体发起委托后先获得后台任务标识；AgentWorks 记录任务状态，并在任务结束时让主智能体取得结果后继续当前工作。
排查委托时，在主智能体实例详情页打开 后台任务，核对任务 ID、目标子代理实例、状态、时间和取消操作。该页当前不显示最终结果正文或完整错误；结果通常体现在主智能体最终回答、相关 Trace 中。参见理解 AgentWorks 如何跟踪每次委托。
子代理等待审批时在哪里处理？
当子代理在飞书触发确认型审批时，审批卡片会显示在主智能体所在会话中。第一次使用前，先通过一项无副作用的调用完成批准和拒绝测试。核对卡片中的操作和参数后作出决定，再确认卡片不再等待审批、后台任务 继续运行或结束，并收到主智能体的最终回复。
如果点击后卡片仍在等待、后台任务没有变化或会话没有最终回复，暂时不要判断本次审批已经成功或失败。请在 Trace、目标工具服务、沙箱运行记录或实际写入的业务系统中核对工具是否执行。不要重复点击卡片，也不要重新发送可能产生副作用的请求。/session fix 只能恢复会话处理新消息，不能确认旧审批的执行结果。
该审批只回答批准或拒绝，不会替业务系统执行用户工具包。用户工具包仍需通过 HTTP 与 WebSocket 接入的应用返回工具结果。参见处理子代理的确认审批和排查飞书审批卡片。
MCP Server 运行在哪里？
MCP Server 运行在 AgentWorks 之外。平台保存远程连接配置并发现工具；在普通控制台配置 MCP Server 时，传输方式为 Streamable HTTP。
MCP 连接测试成功后，智能体就能使用工具吗？
连接测试只确认 AgentWorks 可以访问 MCP Server 并取得工具信息。要让智能体实际使用这些工具，还需要：
- 将 MCP 模板或实例添加到智能体模板。
- 创建或更新智能体实例。
- 发送能够触发目标工具的测试输入。
- 在 Trace 中核对工具名称、参数和结果。
MCP 工具的人工审批在智能体模板的 工具权限 中配置；MCP Server 仍按自身配置验证调用身份和业务权限。参见在智能体实例中验证 MCP 工具。
如何定义自己的沙箱环境配置？
重要
仅限 AgentWorks 平台配置后台
自定义沙箱环境、维护沙箱规格以及将规格分配给租户，需要进入独立的平台配置后台，不是在日常创建智能体的 AgentWorks 控制台中操作。普通用户需要新的环境或规格时，请联系有后台权限的管理员。
普通用户只能选择平台管理员开放的环境。管理员在上述后台的 沙箱环境管理 中配置镜像和工作目录，再把规格分配给租户。
知识库 RAG 模板和实例有什么区别？
在智能体模板的 插件配置 中，知识库 RAG - 模板 对应知识库组模板，知识库 RAG - 实例 对应知识库组实例。“RAG”表示智能体通过检索使用知识，不是另一种知识库资源。
两种方式都不会复制 Collection 中的资料：
- 选择模板时，平台在创建每个智能体实例时，根据所选知识库组模板分别创建知识库组实例。
- 选择实例时，多个智能体可以直接连接同一个已经存在的知识库组实例。
- 两个知识库组实例引用同一个 Collection 时，仍然使用同一份已入库资料。需要隔离资料时，应准备不同的 Collection。
完整资源关系和选择方法参见选择知识库 RAG 模板或实例。
如何确认知识库组实例引用了哪些 Collection？
在 知识库组 中选择 实例，打开目标知识库组实例，再在 引用的知识库集合 中查看配置的 Collection 资源 ID。实例列表中的 集合数 只表示引用数量。
需要确认某次运行实际检索的 Collection 时，请在智能体实例的 Trace 中检查 collection_name。完整操作参见查看知识库组实例引用的 Collection。
知识库模板会同时配置解析、Embedding、重排和检索吗？
不会。知识库组配置用于选择知识库集合和 top_k 等检索参数；文档入库、构建任务和日志在 知识库管理 中处理。
解析器、Embedding 模型、重排器、混合检索和元数据过滤并不统一由知识库模板配置。上线前应使用固定问题检查入库结果、目标集合、实际检索结果和回答。参见配置知识库组和创建集合并导入知识。
记忆库和上下文压缩有什么区别？
上下文压缩用于控制长会话中送入模型的上下文，不会创建或更新记忆库条目；记忆库保存可供智能体后续检索的记忆条目。长会话需要继续使用早期事实时，可以启用上下文压缩；需要把信息保存为记忆条目并在后续交互中检索时，使用记忆库。
“记忆 - 模板”是否也会显示在记忆库管理页面？
不会。记忆库管理 只管理已经创建的记忆库，不提供记忆模板创建入口。可以在智能体模板的插件配置中选择以下两种连接方式：
- 选择 记忆 - 实例：将智能体模板连接到一个现有记忆库。从该模板创建的多个智能体实例都会使用所选记忆库。
- 选择 记忆 - 模板：仅在列表中已有可选模板时使用。创建智能体实例时，平台根据模板为该实例准备一个记忆库资源。
如果 记忆 - 模板 下没有可选项，请联系平台管理员确认当前环境是否提供记忆库模板。只需要一个专用记忆库时，可以选择 记忆 - 实例，但关联该记忆库的智能体模板不应供其他用户创建实例。业务要求每个新实例使用独立记忆库时，不要用一个包含私有数据的现有记忆库代替。
如何让多个智能体实例共享或隔离记忆？
需要有意共享同一份记忆数据时，为这些智能体实例选择同一个 记忆 - 实例。从该模板创建的实例都会连接这个记忆库。不要把个人或私有记忆库连接到供他人复用的智能体模板。
需要每个新建智能体实例使用单独记忆库时，选择环境中可用的 记忆 - 模板。没有可选模板时，可以为每个隔离范围准备单独的智能体模板和现有记忆库，或由调用方业务系统管理按用户区分的长期记忆。配置不同记忆库后，再使用两个测试用户确认双方不能检索对方的测试事实。参见选择记忆库的使用范围。
AgentWorks 会根据渠道用户或 API 调用方自动隔离记忆吗？
同一个现有记忆库是共享数据范围，不会因更换渠道用户、API 调用方或会话而自动拆分。
需要保存个人信息时，请为每个隔离范围使用独立记忆库，或由业务系统管理按用户区分的长期记忆。配置后使用两个测试用户写入相互冲突的测试事实，并分别开始新会话确认双方不能检索对方的内容。参见验证多个调用方的记忆范围。
自动保存后，新会话为什么没有检索到记忆？
使用 AUTO_EXTRACT_AND_TOOL 时，自动保存和调用工具检索是两件事。先确认使用的是相同调用方和同一个记忆库，并在 记忆库管理 中确认自动提取已经完成、条目包含完整事实。
随后开始新会话，在 Trace 中检查是否实际调用了 search_memory。没有调用时，在系统提示词中明确要求智能体先检索已保存的事实；已经调用但没有找到时，检查检索词和记忆条目是否对应。需要逐步核对保存和检索过程时，可使用 TOOL 模式重新测试。
仍然无法检索时，记录智能体实例、记忆库、交互模式、调用方式、测试输入和 Trace，联系平台管理员。参见选择写入和检索方式。
自动保存记忆后，还需要调用检索工具吗？
需要。AUTO_EXTRACT_AND_TOOL 中的“自动”指提取和保存记忆；新会话需要以前的事实时，智能体仍要调用 search_memory，才能把检索结果用于回答。
可以在系统提示词中说明何时检索，再通过 Trace 检查实际调用。参见理解自动处理和工具调用的区别。
智能体能使用某条记忆，为什么管理页面找不到？
记忆库管理 的搜索结果不一定包含智能体曾经使用的所有记忆条目。先核对智能体实例连接的记忆库和资源 ID；搜索不到时，不能据此判断该记忆已经删除。
需要纠正或删除这类内容时，记录调用方、会话、交互模式和测试时间，联系平台管理员确认可见范围。需要每一步都能从 Trace 和管理页面核对时，使用 TOOL。参见理解页面显示的记忆范围。
技能组选择了标有 latest 的 Skill 版本，会自动跟随吗？
不会自动改写技能组中的版本选择。v3 (latest) 表示选中具体的 v3；以后 v4 成为 latest，不会把这里改成 v4。但技能组中的选择也不能保证智能体读取的说明与沙箱挂载文件都锁定到同一版本。发布前应分别验证这两条路径，而不只检查 latest 或 stable 标记。
参见管理 Skill 版本。
测试与排障
长会话越来越慢或接近上下文上限怎么办？
不再需要原对话时，开始新会话。需要继续原任务时，在智能体模板中开启 启用压缩，让主模型自动摘要长会话。更新目标智能体实例后，用固定长会话验证事实保留、工具连续性、延迟和 Token 用量；过大的工具返回应在工具或应用侧缩减。
需要跨会话保存的稳定事实应放入记忆库或业务系统。参见排查长会话上下文压力和配置模型、提示词与上下文压缩。
智能体没有使用已经添加的能力时，应该检查什么？
先在智能体模板详情页的 插件 页签确认关联，再确认测试智能体实例已经更新到最新配置。使用一个必须依赖该能力才能完成的输入测试，并在智能体实例的 Trace 中检查模型是否发起了工具调用以及返回结果。
如果 Trace 中已经出现调用，再根据能力类型检查 沙箱运行记录、知识库构建任务和日志或 后台任务。参见为智能体添加能力和查看 Trace、指标和运行记录。
如何在上线前评估智能体效果？
先创建与生产隔离的预发布智能体实例，使用固定的成功、失败和边界用例通过 网页版对话 或自己的 API 客户端测试，再检查 Trace、工具结果、知识检索、记忆行为、延迟和 Token 用量。对高风险工具还要测试批准、拒绝、超时和重复请求。
AgentWorks 的这些能力支持人工验收和问题定位；评测数据集、自动评分、质量门禁和提示词自动优化需要由外部评测系统或团队流程补充。参见通过预发布验收。
收到待处理中断后，应选择哪个响应动作？
先查看 WebSocket pending 事件中的中断类型，再通过 RespondInterrupt 回传原 msg_id、user_id、会话的 context_key 和该项 interrupt_id：
- 工具等待人工审批时，使用
APPROVE或REJECT。 - 中断要求用户补充信息时，使用
RESPOND并返回输入内容。 - 用户工具包等待调用方执行工具时，先执行工具，再使用
RESPOND返回符合工具输出结构的结果。 - 无法提供所需输入或工具执行失败时，使用
ERROR。
如果用户工具包中的工具调用先经过人工审批，APPROVE 只允许调用继续，不会替你的应用执行工具或返回业务结果。完成中断处理前，不要用新的普通消息代替中断响应。参见响应中断和在你的应用中执行用户工具。
多个工具调用都需要审批或输入时，可以同时处理吗？
可以，但应逐项识别。网页版对话支持逐项批准或拒绝，也提供 全部批准 和 全部拒绝；选择全部批准时还要再次确认。飞书则按收到的审批卡片操作。
自己开发 API 客户端时，以每个 pending.id 跟踪和响应，不要按工具名称或显示顺序猜测对应关系。审批决定与用户工具执行结果是两种不同响应；不要用一次 APPROVE 代替所有工具结果。参见按接入方式处理审批和响应中断。
在哪里查看工具调用、Token 用量和后台任务？
在智能体实例的 Trace 中查看输入、模型执行、工具调用、结果、耗时和中断；在工作台查看调用量、成功情况和 Token 用量；在 沙箱运行记录、知识库任务日志和 后台任务 中继续定位对应能力。
这些页面用于排查当前实例及相关能力的运行问题。参见查看 Trace、指标和运行记录。
status 事件表示本次运行已经完成吗？
不表示。进度提示、连接在线和消息提交成功都不是运行完成。API 客户端应匹配事件帧的 mid 与原输入的 msg_id，识别主智能体生命周期：success、error 或 cancelled 才是终止阶段；retry 表示正在重试，has_pending_interrupt 表示仍需处理，都还没有结束。不要把带有 sub 的子任务结束事件当作整个请求完成。
提交审批或工具结果后没有收到终止事件时，保留用户、会话、请求和中断标识，核对事件流中的待处理项、Trace 与外部系统结果；断线先续传，收到 reset 后才用历史和待处理中断查询重建状态。不要盲目重发可能产生副作用的请求。参见接收运行事件和响应中断。
API 调用返回 HTTP 200 就表示业务成功吗？
不表示。先检查 HTTP 状态与 JSON 信封中的 success_response；业务失败也可能使用 HTTP 200，应继续查看 data.reason。即使 SendMessage 成功，也只表示请求已被接收；还要检查该次运行的终止事件，以及工具或外部系统中的实际业务结果。
运行、安全与治理
能否停止一个智能体实例？
需要暂停访问时，先在调用方停止流量，再按影响范围停用 Token、停用或改绑渠道。Token 停用不保证已经建立的连接立即断开；完整处置见轮换凭证并撤销访问。
Agent API Token、WebSocket Token 和控制台登录身份可以互换吗？
不能。调用智能体的 HTTP 请求和 WebSocket 握手使用对应渠道的 WebSocket Token；控制台登录身份用于管理产品对象。请为目标渠道账号创建 Token，并将它保存在业务服务后端。
更换或撤销已有 Token，参见Token 轮换流程；使用旧 Agent API Token 的客户端，参见Direct Invoke 迁移步骤。
如何访问 AgentWorks 平台配置后台？
AgentWorks 平台配置后台用于管理租户资源分配、沙箱规格和环境，使用独立入口。需要操作这些平台设置时，请向平台提供方确认后台地址、登录方式和访问权限；创建智能体、管理渠道和给成员授权，使用日常的 AgentWorks 控制台即可。
AgentWorks 提供哪些运行和治理控制？
可用控制包括超时和自动重试、备用模型、沙箱规格和环境、智能体实例状态和配置同步、资源访问权限、Token、渠道用户绑定、Trace、调用和 Token 指标、沙箱运行记录及知识库入库日志。控制台显示统一导航及插件选项，不通过租户能力类型开关隐藏入口。
组织级审批、自动评测、合规审计和预算管理需要通过现有企业流程或外部系统完成。
兼容性与迁移
熟悉其他智能体平台时，如何理解 AgentWorks 的会话和记忆库？
不同产品使用 memory 表示的对象并不相同。理解 AgentWorks 时，应先确认需要延续的是当前对话、跨会话事实、维护过的资料，还是工作流执行状态：
- 对话历史或窗口记忆：最接近 AgentWorks 的会话上下文。通过 API 调用时，平台按渠道身份和会话信息继续对话；开始新会话后不会继续原会话上下文。
- Thread 或 Checkpointer State：只需要延续对话时，最接近会话上下文；需要保存节点状态、检查点、重试进度或分支结果时，应由调用应用或外部编排系统管理。
- Long-term Memory、Store、Memory Bank 或 Memory Collection：需要跨会话保存事实和偏好时，最接近 AgentWorks 的记忆库。连接现有记忆库前，还需要确认多个智能体实例是否应共享其中的条目。
- 文档语料或向量资料库：需要检索经过维护和入库的资料时，应使用知识库，不应把这类内容作为记忆条目重复保存。
这些对应关系用于帮助理解产品概念，不表示 API、数据格式、存储范围或运行机制兼容。第一次使用记忆库时，请从一个专用测试记忆库和 TOOL 交互模式开始，完成写入、新会话检索、纠正和删除验证。参见理解 AgentWorks 如何使用记忆和完成第一次安全验证。
其他平台中由调用方执行工具的功能，在 AgentWorks 中对应什么？
在 AgentWorks 中，最接近的能力是用户工具包：模型选择工具后，AgentWorks 暂停当前调用并把工具名称和参数作为中断返回；通过 HTTP API 和 WebSocket 事件接入的应用处理这个中断、执行实际操作，再返回 RESPOND 或 ERROR，智能体随后继续处理。
| 熟悉的功能 | 与用户工具包的相似之处 | 需要注意的区别 |
|---|---|---|
| Microsoft Copilot Studio Client tools | 最接近的产品级功能：智能体把工具输入交给客户端，等待客户端执行并返回结果，然后继续编排 | Copilot Studio 使用事件活动和客户端工具注册；AgentWorks 使用智能体模板中的用户工具包，以及 pending 中断事件、RESPOND 和 ERROR |
| Amazon Bedrock Agents Return control | 最接近的 API 级功能：InvokeAgent 返回操作及参数，应用执行后使用同一个调用标识返回结果 | 这是 Bedrock Agents Action Group 的能力，不属于 AgentCore Gateway；AgentWorks 通过用户工具中断完成交接 |
LangGraph interrupt() 和恢复运行 | 可以实现“暂停运行 → 调用方执行 → 返回结果 → 恢复运行”的相同模式 | 这是代码级原语；开发者需要自行设计工具契约、持久化和调用方集成，普通 LangGraph 工具通常仍在 LangGraph 进程中执行 |
这些功能的交互模式相近，但配置对象、消息格式和运行状态并不兼容，不能直接导入或替换。迁移时，应在智能体模板中重新定义用户工具，并让接入应用按照 AgentWorks 的中断协议执行和返回结果；参见确认接入方式能够处理工具中断。
AgentWorks 支持同一轮多工具调用吗？
可以处理，但前提是所选模型和模型接口一次返回多个工具调用。平台不能强制不支持该能力的模型一次生成多个调用。
WebSocket 会持续推送工具事件。多项事件可能来自不同轮次，也不证明工具同时执行；应按工具调用 ID 关联参数与结果。参见验证多个工具调用与结果的关联。
一次返回多个工具调用，表示它们会并行执行吗？
不表示并行执行。模型一次提出多个调用、事件流包含多项或卡片同时显示多项，都不能证明工具实际同时执行。AgentWorks 当前不提供用户可配置的工具并发数或执行顺序，也不承诺通过重叠执行降低延迟。
业务流程需要精确控制并行、顺序、重试、取消、超时或部分失败时，应在外部编排系统或智能体框架中定义这些步骤，再通过 API 调用 AgentWorks 智能体实例。参见AgentWorks 可以定义自定义编排循环吗？。
AgentWorks 可以定义自定义编排循环吗？
AgentWorks 管理一次运行中的模型请求、能力调用、流式事件、会话和中断。Todo 帮助模型整理当前任务的步骤，子代理让模型按需委托已有智能体实例。构建者负责配置模型、提示词、能力和权限，不需要为这些运行步骤绘制流程图。
如果需要由构建者精确控制节点、状态、条件路由、并行、重试、循环和终止条件，请在外部编排系统或智能体框架中定义这些步骤。外部系统保存编排状态，通常通过 API 调用 AgentWorks 智能体实例。调用时通过 HTTP 提交请求，通过 WebSocket 订阅回复和运行事件。选择接入方式后，还应遵循处理多个待审批调用和判断流式运行是否完成中的要求。AgentWorks 提供可调用的智能体步骤，不运行该外部流程。
如果你熟悉 LangGraph graph、Copilot Studio 或 Gemini Flow，以及 CrewAI Flow，可以把它们理解为可选的外部编排方式；AgentWorks 的单次运行循环和子代理委托不等同于外部编排。参见区分平台单次运行和可选的外部编排。
主智能体如何知道子代理能做什么？
AgentWorks 会在运行时向主智能体提供已关联子代理的名称和描述。主智能体结合这些信息、当前请求和自身的系统提示词判断是否委托。
主智能体不会自动读取子代理使用的模型、完整系统提示词、插件、权限或测试结果。因此，应让名称和描述清楚说明子代理的职责、所需输入、返回结果和不适用范围，并在关联前独立验证目标实例。名称和描述只帮助主智能体选择目标，不能代替实际的权限限制。参见让主智能体看懂每个子代理适合做什么。
子代理和 Copilot Studio 的生成式编排相同吗？
两者都可以让模型根据用户输入、系统提示词和可用能力决定直接回答、调用工具或委托其他智能体。AgentWorks 的 子代理 用于把任务异步委托给已经配置的智能体实例，再由主智能体取得结果并完成回答。
AgentWorks 不会根据一段自然语言说明自动生成主题、触发器或流程配置，也不显示一份可编辑的运行计划。主智能体根据系统提示词以及子代理的名称和描述选择委托目标；需要固定业务路由、各业务环节的重试次数、循环条件或终止条件时，由外部流程负责这些控制。这不同于平台对模型、工具调用或整次任务提供的超时和自动重试。参见让主智能体看懂每个子代理适合做什么。
AgentWorks 是否支持 A2A？子代理是否通过 A2A 通信？
AgentWorks 的 子代理只能选择已经存在的 AgentWorks 智能体实例。委托任务通过 后台任务查看状态和结果；配置时不填写 Agent Card 或 A2A 服务地址。因此，子代理不是 A2A 接入，后台任务也不是 A2A Task。
AgentWorks 提供 HTTP API 和 WebSocket 事件协议，不提供 Agent Card 或 A2A 任务端点。需要组合独立部署的外部智能体时，请在外部系统中保留协调和编排逻辑，再通过目标部署提供的智能体调用 API 调用 AgentWorks。调用时通过 HTTP 提交请求，通过 WebSocket 订阅回复和运行事件。需要接入外部工具、API 或数据资源时，使用 MCP 或用户工具包。
不要把 A2A 的 Task 或上下文标识直接映射为 AgentWorks 的调用任务、后台任务或 sid；它们属于不同的接口契约。参见区分子代理、可选的外部编排和工具调用和区分接入方式。
可以直接托管 LangGraph、CrewAI 或其他框架代码吗？
不能直接上传并托管这些框架的运行项目。AgentWorks 运行由控制台配置创建的智能体实例，不提供任意框架代码的通用托管入口。
已有 LangGraph、CrewAI、ADK、Strands、LlamaIndex 或自定义服务可以继续在外部运行，再通过 API 调用智能体实例，或者通过 MCP 和用户工具包向智能体提供能力。这是系统集成，不是把原有运行时迁移到 AgentWorks。
AgentWorks 是否提供 LangGraph、ADK 或 CrewAI 的专用适配器？
AgentWorks 提供通用 HTTP API 和 WebSocket 事件协议，不提供 LangGraph、ADK 或 CrewAI 的专用适配器。
外部框架仍在自己的运行环境中执行。集成方负责发送消息、订阅结果，保存用户、业务对话、sid 和 mid 的对应关系，并处理工具中断、重试、终止和跨系统排障。参见保存业务进度和调用记录。
可以从 Git 仓库、ZIP 或 CLI 导入并部署智能体项目吗？
不能通过通用 Git 仓库、项目 ZIP 或 CLI 部署智能体运行项目。智能体模板和智能体实例通过控制台管理。
Skill 支持 ZIP 导入和导出，但 ZIP 只包含 SKILL.md 和相关文件，不等于完整智能体或编排运行时。智能体可以按需读取这些资源，但平台不会把 ZIP 当作代码项目部署、安装依赖或自动运行脚本。已有代码项目应保留在原有运行环境中，并通过 API、MCP 或用户工具包接入。
可以在每次 API 调用时临时更换模型或插件吗？
不能通过 HTTP SendMessage 临时覆盖模型或插件。模型、提示词和插件属于智能体模板及其实例配置；发送消息、响应中断和取消运行分别使用对应接口。
需要另一套模型和能力组合时，创建或更新对应智能体模板和实例，并分别完成测试。
可以查看、修改、回放或分叉智能体运行状态吗？
可以通过 Trace 查看输入、模型执行、工具调用、结果和中断。HTTP 接口还提供历史消息和待处理中断查询，是否可用取决于目标环境配置。
事件重放用于补收消息，不会让智能体回到过去的执行点。智能体调用 API 不提供任意状态编辑或从检查点分叉接口。连接中断后，应先恢复订阅、核对待处理中断与已有结果，再决定下一步；不要把重新发送业务请求当作恢复连接。参见管理会话和中断。
如何把其他平台的会话和任务标识对应到 AgentWorks？
先区分会话和一次执行，再映射标识：
| 熟悉的标识 | AgentWorks 中最接近的概念 | 区别 |
|---|---|---|
LangGraph thread_id | 会话标识 sid | 用于关联对话，不等于检查点历史、回放或分叉 |
Dify conversation_id、Flowise sessionId | 会话标识 sid | 不能直接互换值；还要保留正确的渠道用户和消息信息 |
AgentCore runtimeSessionId | 没有一一对应项 | AgentWorks 会话标识不会自动创建专属运行环境 |
CrewAI AMP kickoff_id | 消息请求 mid | 一个会话可以包含多次请求；每次请求分别判断结束 |
Copilot Studio New chat | 开始新会话 | 网页版对话选择“开启新对话”；渠道使用 /session new |