跳转到内容

组织模板

使用 Organization API Key 管理共享 AgentTemplate。创建 Session 时显式选择该模板。

方法与路径 用途
GET /api/v1/org/agent-template-reference-catalog 查看模型、Sandbox 和已发布 Skill 的选择及可用性。
GET /api/v1/org/agent-templates 按筛选、排序和游标分页列出模板。
POST /api/v1/org/agent-templates 原子创建带有完整初始内容的模板。
GET /api/v1/org/agent-templates/{templateId} 读取模板及其当前公开配置。
PUT /api/v1/org/agent-templates/{templateId} 原地替换完整公开配置。
POST /api/v1/org/agent-templates/{templateId}/archive 归档模板。

创建和替换请求体包含 displayName 与 content。Content 使用 API 参考中的完整公开模板规范;参考目录帮助选择可用依赖。可选的 standingTask: {"goal": "..."} 让语音对话中持续运行一个 Full Agent 任务,见常驻任务。PUT 替换完整配置,因此省略 standingTask 的替换会移除它。GET 返回 template 摘要和当前 content;每个摘要都带有模板 etag 和当前 contentDigest。

通过 content.tools.mcp 关联本组织可用的共享 MCP Server Registration 和 Connector。每项格式为 {"serverId": "<registration-id>"}。MCP Server Registration 的引用项可以添加 "toolNames": ["<remote-tool-name>", ...],模型只会看到该注册中列出的工具;省略时模型可以看到全部工具。目录中不存在的名称会被忽略。修改列表会改变模板的 contentDigest,已有会话在切换模板之前继续使用创建时的列表。Connector 引用项不接受 toolNames。创建时省略 tools 会得到空引用列表。替换时省略 tools 会保留当前引用。提交完整列表可替换引用,提交 "tools": {"mcp": []} 可清空引用。当前模板内容包含这些引用。重试已提交的命令会返回原始响应,旧响应可能省略 tools。

Template 引用的每个 MCP Server Registration 都是每个新 Turn 的必需依赖。若某个 Registration 的 MCP Authorization 不可用,Turn 会在开始前被拒绝,返回 409 mcp_authorization_required;details.registrations 列出每个这样的 Registration 及其 serverId、owner 和 reason(missing、invalid、revoked 或 insufficient_scope)。在 End User 模式下,这是拥有该 Session 的 End User 的 Authorization。如果 Authorization 在 Turn 进行中失效(被撤销,或服务器对调用返回 HTTP 401 或 403),该 Turn 会以相同的代码和 details 失败,见 agent.session.turn.failed 事件和 Turn 的 failure,而不会在缺少该服务器的情况下继续执行。已停用或已删除的 Registration 会以 409 session_execution_dependency_unavailable 拒绝 Turn。修复该 Authorization(例如重新设置 token,或重新通过 OAuth 授权)后,发起新的 Turn 即可,之前的对话会保留。若要在 Turn 被拒绝之前请 End User 完成授权,请读取其授权需求。

创建或替换立即生效。每个 Session Configuration Epoch 保留准入时的模板内容与摘要。PUT 需要在 If-Match 中传入带引号的模板 ETag。Console 编辑和 API 写入共享同一个模板及其 ETag。ETag 过期后,先读取当前模板,再准备新的编辑。

在创建 Session时提交 agentTemplateId,可一并设置该 Session 的补充指令、Sandbox Profile 与工作目录。已准入的 Configuration Epoch 保留当时的模板内容和摘要。要改变同一 Session 的行为,显式发起 Template 切换。归档后的模板无法再次选用,已有的 Configuration Epoch 仍可读取。