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