人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载本篇技术指南以 RikkaHub 仓库中 .agents/skills/claude-api/shared/managed-agents-tools.md 为核心骨架系统讲解 Anthropic Managed Agents 的三类工具预构建 Agent 工具、MCP 工具、自定义工具、权限策略、MCP 服务器声明与凭据分离的 Vault 机制以及 Skills 技能体系。读者将掌握如何为持久化 Agent 配置工具与权限、如何安全地注入第三方凭据而绝不落入沙箱、如何声明 MCP 服务器并通过agent.custom_tool_use/user.custom_tool_result事件流驱动客户端自定义工具最终能够独立搭建一个具备文件操作、bash、联网搜索与领域技能的多模态智能体会话。该文档是 RikkaHub 仓库内claude-api技能SKILL.md 声明其为 Claude API / Anthropic SDK 的参考实现覆盖 model ids、params、streaming、tool use、MCP、agents、caching 等中关于 Managed Agents 工具面的核心分册配套的shared/managed-agents-*.md系列文档共同构成完整参考其中 SKILL.md 的 Managed Agents (Beta) 一节给出了完整的阅读路线图。工具全景三类工具的定位与执行边界Managed Agents 把谁运行工具作为第一层设计决策。文档给出了一个清晰的三分法对照表类型谁运行它工作机制Prebuilt Claude Agent toolsagent_toolset_20260401Anthropic在会话的容器内执行cloud环境若为self_hosted则由你的 worker提供并运行见 managed-agents-self-hosted-sandboxes.md文件操作、bash、网页搜索等。可整体启用也可用enabled: true/false逐个配置MCP toolsmcp_toolsetAnthropic 的编排层由已连接的 MCP 服务器暴露的能力通过 toolset 按服务器授予访问Custom tools你——你的应用处理调用并返回结果Agent 发出agent.custom_tool_use事件会话进入idle你回发user.custom_tool_result事件从 managed-agents-core.md 的架构图可以更直观地理解这层边界Agent配置对象→ Anthropic 编排层agent loopClaude 工具调用→ 环境模板 → 容器工具执行工作区。Agent 循环本身不运行在容器里容器只是工具的执行场所这正是预构建工具由 Anthropic 在容器内运行、自定义工具由你的应用运行这一分工的根源。文档给出的核心建议通过agent_toolset_20260401一次性启用全部预构建工具然后按需逐个禁用——比白名单式逐项开启更省事也更容易排查缺工具类问题。关于版本化toolset 是版本化的静态资源。底层工具发生变化时会创建新的 toolset 版本因此命名为_20260401保证你始终确切知道拿到的是什么能力集合。这与 Agent 本身的不可变版本机制每次POST /v1/agents/{id}更新都会产生新的不可变版本一脉相承。Agent Toolset 内置工具与整体启用agent_toolset_20260401提供以下 8 个内置工具工具描述bash在 shell 会话中执行 bash 命令read从本地文件系统读取文件支持文本、图片、PDF 与 Jupyter notebookwrite向本地文件系统写入文件edit在文件中执行字符串替换glob基于 glob 模式的快速文件匹配grep基于正则表达式的文本搜索web_fetch从 URL 抓取内容web_search联网搜索信息整体启用只需在 Agent 的tools数组中声明该 toolset{ tools: [ { type: agent_toolset_20260401 } ] }注意tools是POST /v1/agents的顶层字段最多 128 个永远不要把它放到sessions.create()的请求体里——会话只持有 Agent 的指针字符串 ID 或{type: agent, id, version}。这是 managed-agents-overview.md 强调的强制流程Agent创建一次→ Session每次运行。逐工具配置default_config 与 configs 覆盖默认配置对 toolset 内所有工具生效configs数组则提供单工具覆盖。以下示例启用全部工具唯独关闭 bash{ tools: [ { type: agent_toolset_20260401, default_config: { enabled: true }, configs: [ { name: bash, enabled: false } ] } ] }字段说明字段必填说明type✅agent_toolset_20260401default_config❌应用于所有工具形如{ enabled: bool, permission_policy: {...} }configs❌单工具覆盖形如[{ name: ..., enabled: bool, permission_policy: {...} }]反向的白名单模式同样支持——把 default 关掉、按需逐个开启{ tools: [ { type: agent_toolset_20260401, default_config: { enabled: false }, configs: [ { name: bash, enabled: true }, { name: read, enabled: true } ] } ] }权限策略自动执行与人工审批权限策略控制由服务器执行的工具Agent toolset MCP 工具何时自动运行、何时等待审批。它不适用于自定义工具——因为自定义工具本来就是在你的应用里执行的。策略行为always_allow工具自动执行默认always_ask会话发出session.status_idle并暂停直到你发送tool_confirmation事件配置示例——默认全自动但 bash 每次调用都需要审批{ type: agent_toolset_20260401, default_config: { enabled: true, permission_policy: { type: always_allow } }, configs: [ { name: bash, permission_policy: { type: always_ask } } ] }响应always_ask向会话发送user.tool_confirmation事件tool_use_id取自触发事件的agent_tool_use/mcp_tool_use事件{ type: tool_confirmation, tool_use_id: sevt_abc123, result: allow } { type: tool_confirmation, tool_use_id: sevt_def456, result: deny, message: Read .env.example instead }deny时附带的message会回传给 Agent让它调整方案。结合 managed-agents-client-patterns.md 的tool_confirmation往返模式Pattern 4可以看到完整闭环当事件携带evaluated_permission ask时客户端对每个待审批的agent.tool_use事件回发一次user.tool_confirmation其中tool_use_id是事件 ID通常形如sevt_...而不是toolu_...形式的 ID。自定义工具客户端执行的五步流程自定义工具由你的应用执行而非 Anthropic。完整流程为Agent 决定使用工具 → 会话发出携带 inputs 的agent.custom_tool_use事件会话进入idle等待你处理你的应用执行工具你回发携带输出的user.custom_tool_result事件会话恢复running自定义工具不需要权限策略——因为执行者是你自己。声明一个自定义工具只需type: custom、name、description和 JSON Schema 形式的input_schema{ tools: [ { type: custom, name: get_weather, description: Fetch current weather for a city., input_schema: { type: object, properties: { city: { type: string, description: City name } }, required: [city] } } ] }managed-agents-events.md 给出了完整的接收/发送事件类型agent.custom_tool_use表示 Agent 调用了自定义工具会话进入 idle你通过user.custom_tool_result提供结果。Python 侧的完整流式循环在 python/managed-agents/README.md 中有可直接运行的实现——收集一次 idle 前全部agent.custom_tool_use事件批量执行后一次性回发结果with client.beta.sessions.events.stream(session_idsession_id) as stream: tool_calls [] for event in stream: if event.type agent.custom_tool_use: tool_calls.append(event) elif event.type session.status_idle: break elif event.type session.status_terminated: return results [ { type: user.custom_tool_result, custom_tool_use_id: call.id, content: [{type: text, text: run_custom_tool(call.name, call.input)}], } for call in tool_calls ] client.beta.sessions.events.send(session_idsession_id, eventsresults)自定义工具是凭据不入沙箱的最后兜底方案client-patterns.md Pattern 9当无法使用 Vault例如self_hosted沙箱暂不支持environment_variable凭据、或客户端会对占位符做本地格式校验、或密钥绝不能离开你的基础设施时把需要认证的调用移到你自己的编排进程里——agent.custom_tool_use通过你已持有的 SSE 事件流到达user.custom_tool_result通过events.send()返回容器永远看不到密钥。切忌把 API key 塞进 system prompt 或用户消息里作为变通——它们会持久化在会话的事件历史中可被events.list()读取并进入压缩摘要。MCP 服务器声明与凭据的强制分离MCPModel Context Protocol服务器暴露标准化的第三方能力如 Asana、GitHub、Linear。配置被拆到 Agent 和 Vault 两个对象上这是安全设计的核心Agent 创建时只声明连接哪些服务器type、name、url——不含任何认证信息Agent 的mcp_servers数组没有 auth 字段。Vault存放 OAuth 凭据通过vault_ids在创建会话时挂载。这样可复用的 Agent 定义中不携带任何密钥。每个 Vault 凭据绑定一个 MCP 服务器 URLAnthropic 按 URL 将凭据匹配到服务器。Agent 侧——声明服务器无认证字段必填说明type✅urlname✅唯一名称由mcp_toolset.mcp_server_name引用url✅MCP 服务器的端点 URLStreamable HTTP 传输{ mcp_servers: [ { type: url, name: linear, url: https://mcp.linear.app/mcp } ], tools: [ { type: mcp_toolset, mcp_server_name: linear } ] }会话侧——挂载 Vault{ agent: agent_abc123, environment_id: env_abc123, vault_ids: [vlt_abc123] }文档特别标注了几条实战经验标注为empirical按工具启用 MCP toolsetmcp_toolset已被观察到接受default_config: {enabled: false}configs: [{name, enabled: true}]实现白名单模式而 API 参考只展示{type, mcp_server_name}最小形式。运行中会话改工具sessions.update()可在会话idle时替换agent.tools、agent.mcp_servers和vault_ids——这是会话级局部覆盖不动 Agent 对象。结合 core.md 可知只有tools和mcp_servers能在会话创建后变更且传入的数组是整体替换要追加一个工具需先 GET 再 POST 回。大输出自动落盘MCP 工具返回超过100K token时输出会自动卸载到沙箱中的文件Agent 收到截断预览 文件路径可用read读取完整内容无需任何配置。无效 Vault 凭据不阻断会话创建会话仍会成功创建session.error事件会描述 MCP 认证失败并在下一次idle → running转换时重试认证。⚠️MCP 认证令牌 ≠ REST API 令牌。托管的 MCP 服务器mcp.notion.com、mcp.linear.app等通常要求OAuth bearer token而不是服务商的原生 API key。Notion 的ntn_integration token 只能通过其 REST API 认证不能作为 Notion MCP 服务器的 Vault 凭据——它们是两套不同的认证系统。Vault凭据仓库与沙箱安全边界Vault存储由 Anthropic 替你管理的凭据分两类MCP 凭据mcp_oauth、static_bearer——以mcp_server_url为键。Agent 连接该 URL 的服务器时自动注入令牌mcp_oauth令牌通过标准 OAuth 2.0refresh_tokengrant 自动刷新。这是认证 MCP 服务器的唯一途径。环境变量凭据environment_variable——以secret_name环境变量名为键。沙箱中只能看到不透明占位符真实密钥在**出口egress**处被替换进外发请求。适用于任何通过环境变量认证的服务CLIaws、gcloud、stripe、SDK或从bash工具直接发起的curl。你提供的密钥字段token、access_token、refresh_token、client_secret、secret_value是只写的——永远不会出现在 API 响应中。凭据与沙箱的隔离Vault 存凭据但凭据绝不进入沙箱。这是一道刻意的安全边界沙箱中运行的任何代码包括 Agent 写出的脚本都无法读取或外泄 vault 凭据即使在提示注入攻击下也不行。凭据由 Anthropic 侧的代理在请求离开沙箱之后注入MCP 工具调用经由 Anthropic 侧代理路由代理从 vault 取凭据并附加到外发请求。已挂载 GitHub 仓库的 git 操作git pull、git push、GitHub REST 调用经由 git 代理注入github_repository资源的authorization_token方式相同。相关细节见 managed-agents-environments.md该 token 绝不进入容器且生成 PR 还需要额外挂载 GitHub MCP 服务器vault 认证。环境变量凭据在沙箱中表现为不透明占位符仅在向凭据的allowed_hosts许可主机发请求时于出口处替换为真实值。当 Vault 凭据不适用时例如self_hosted沙箱文档再次指向注册自定义工具方案——你的编排进程已持有凭据通过同一认证事件流执行调用并返回结果不暴露任何公共端点。创建与使用 Vault 的流程创建 vaultclient.beta.vaults.create(...)——每个租户/用户一个或共享一个取决于你的模型向其中添加凭据client.beta.vaults.credentials.create(...)——MCP 凭据以 MCP 服务器 URL 为键环境变量凭据以secret_name为键创建会话时通过vault_ids: [vlt_...]引用Anthropic 在令牌过期前自动刷新 OAuth 令牌并在运行时替换密钥MCP OAuth 凭据的完整形态{ display_name: Notion (workspace-foo), auth: { type: mcp_oauth, mcp_server_url: https://mcp.notion.com/mcp, access_token: current access token, expires_at: 2026-04-02T14:00:00Z, refresh: { refresh_token: refresh token, client_id: your OAuth client_id, token_endpoint: https://api.notion.com/v1/oauth/token, token_endpoint_auth: { type: none } } } }refresh块就是自动刷新的开关——token_endpoint是 Anthropic 发送refresh_tokengrant 的地方。token_endpoint_auth是一个判别联合type形态适用场景none{type: none}公共 OAuth 客户端无 secretclient_secret_basic{type: client_secret_basic, client_secret: ...}机密客户端secret 走 HTTP Basic authclient_secret_post{type: client_secret_post, client_secret: ...}机密客户端secret 在请求体中如果只有 access token、没有刷新能力可以整体省略refresh——凭据在过期前一直有效过期后 Agent 失去访问。环境变量凭据的完整形态{ display_name: Twilio API key for sandbox, auth: { type: environment_variable, secret_name: TWILIO_API_KEY, secret_value: sk-your-secret-here, networking: { type: limited, allowed_hosts: [api.twilio.com, *.twilio.com] } } }networking.allowed_hosts控制该密钥可以被替换进哪些外发主机——可选{type: limited, allowed_hosts: [...]}或无法预先枚举域名时的{type: unrestricted}。强烈建议使用 limited它防止密钥被发送到未授权主机。injection_location可选networking的兄弟字段控制密钥被替换到外发请求的哪个部位——{header: bool, body: bool}。两者相互独立allowed_hosts限定哪些主机的请求可以使用该密钥injection_location限定跨所有这些主机时密钥被替换进请求的哪些部分。多数服务从请求头读取 API key因此{header: true}是更窄的配置——请求体常由 Agent 正在处理的内容拼装是更大的暴露面。未启用位置上的占位符既不会被替换也不会被剥离——字面量的不透明占位符字符串会被原样发送给第三方。操作injection_location语义创建凭据省略整个字段 → 两个位置都启用提供对象 → 省略的字段默认为false{header: true}创建仅 header 的凭据更新凭据字段逐项合并——{body: false}禁用 body 替换而保持 header 不变运行中会话的更新在下次操作时生效一条凭据至少启用一个位置会让两个位置都禁用的创建/更新返回 400对对象或任一字段显式传null同样报 400应省略。响应始终返回两个字段的解析值。⚠️两个网络层缺一不可。凭据上的networking.allowed_hosts控制哪些请求使用密钥而不是哪些请求被允许。Agent 还必须能在环境层触达该域名unrestricted或域名列在环境的allowed_hosts中见 managed-agents-environments.md。任一层缺失密钥替换请求都会失败。⚠️客户端本地校验的坑。替换发生在出口而非沙箱内——在发起网络请求前本地校验凭据格式的客户端例如检查 key 是否以sk-开头的 CLI会看到不透明占位符而启动失败。最小化密钥权限。Agent 能做该密钥允许的一切权限过宽的密钥会放大意外行为时的爆炸半径。与self_hosted沙箱的兼容性environment_variable凭据依赖 Anthropic 托管的出口自托管沙箱不支持详见 managed-agents-self-hosted-sandboxes.md 的 cloud-vs-self-hosted 对照表。所有凭据类型的约束每个 Vault 键唯一——MCP 凭据的mcp_server_url与环境变量凭据的secret_name在活跃凭据中必须唯一重复返回 409。键不可变——密钥值、display_name、环境变量凭据的injection_location可更新要改mcp_server_url、secret_name、token_endpoint或client_id需归档旧凭据并新建。归档会清除密钥并释放该键。每个 Vault 最多 20 条凭据。凭据按提交时原样存储到会话运行时才校验——无效凭据表现为会话中的认证或下游错误会被发出但不会阻断会话继续。作用域Vault 是 workspace 级的。API workspace 中 developer 角色可创建、读取仅元数据——密钥只写和挂载 Vault。vault_ids只能在会话创建时设置不能通过会话更新修改SDK docstring 明确Not yet supported; requests setting this field are rejected。Skills按需加载的领域专家能力Skills是基于文件系统的可复用资源为 Agent 提供领域专长——工作流、上下文与最佳实践把通用 Agent 变成专家。与 prompt一次性任务的会话级指令不同skill按需加载免去在多次对话中重复提供相同指导。两种类型工作机制相同——Agent 在任务相关时自动使用类型是什么Pre-built Anthropic skills常见文档任务PowerPoint、Excel、Word、PDF按名称引用如xlsxCustom skills你通过 Skills API 在组织内创建的技能按skill_id 可选version引用每个 Agent 最多 20 个 skill。Agent 创建使用managed-agents-2026-04-01beta独立的 Skills API管理自定义技能定义使用skills-2025-10-02。在会话中启用 SkillsSkill 附加在Agent定义上通过agents.create()传入const agent await client.beta.agents.create( { name: Financial Agent, model: claude-opus-4-8, system: You are a financial analysis agent., skills: [ { type: anthropic, skill_id: xlsx }, { type: custom, skill_id: skill_abc123, version: latest }, ], } );Python 等价写法agent client.beta.agents.create( nameFinancial Agent, modelclaude-opus-4-8, systemYou are a financial analysis agent., skills[ {type: anthropic, skill_id: xlsx}, {type: custom, skill_id: skill_abc123, version: latest}, ] )Skill 引用字段字段Anthropic skillCustom skilltypeanthropiccustomskill_id技能名称如xlsx、docx、pptx、pdfSkills API 返回的技能 ID如skill_abc123version—latest或具体版本号Skills API 端点操作方法路径Create SkillPOST/v1/skillsList SkillsGET/v1/skillsGet SkillGET/v1/skills/{id}Delete SkillDELETE/v1/skills/{id}Create VersionPOST/v1/skills/{id}/versionsList VersionsGET/v1/skills/{id}/versionsGet VersionGET/v1/skills/{id}/versions/{version}Delete VersionDELETE/v1/skills/{id}/versions/{version}需要注意SKILL.md 明确区分Agent Skills ≠ Managed Agents——要让 Claude 通过 Agent Skills 生成.pptx/.xlsx等文档应调用client.beta.messages.create带container{skills: [...]}与code_execution工具而非client.beta.agents/sessions面。端到端整合从环境到 Agent 再到带凭据的会话把以上所有要素串起来一个典型的完整流程是Python 示例完整版见 python/managed-agents/README.md# 1. 创建环境一次——容器运行的模板 environment client.beta.environments.create( namemy-dev-env, config{type: cloud, networking: {type: unrestricted}}, ) # 2. 创建 Agent一次持久化且版本化——模型、system、tools、mcp_servers、skills 都在这 agent client.beta.agents.create( nameMCP Agent, modelclaude-opus-4-8, systemYou are a helpful coding agent., mcp_servers[ {type: url, name: my-tools, url: https://my-mcp-server.example.com/sse}, ], tools[ {type: agent_toolset_20260401, default_config: {enabled: True}}, {type: mcp_toolset, mcp_server_name: my-tools}, ], ) # 3. 每次运行创建会话——仅引用 agent environment并挂载 vaultMCP 凭据 session client.beta.sessions.create( agent{type: agent, id: agent.id, version: agent.version}, environment_idenvironment.id, vault_ids[vault.id], ) print(fTrace: https://platform.claude.com/workspaces/default/sessions/{session.id})三个必须养成的习惯Agent 先于会话绝不例外——model/system/tools都是POST /v1/agents的顶层字段会话只接受字符串 ID 或{type: agent, id, version}指针。Agent 只创建一次——把agents.create()放进 setup 脚本或if agent_id is None:保护块而不是热路径每次运行只sessions.create()。否则会累积孤儿 Agent 对象并白白支付创建延迟。Stream-first——先打开 SSE 事件流再发送 kickoff 事件否则早期事件包括快速状态转换会以缓冲批次到达丢失实时反应能力见 managed-agents-events.md 的 Steering Patterns。延伸阅读managed-agents-tools.md——本文核心参考Tools、MCP、Vaults、Skills 原始出处managed-agents-overview.md——强制流程Agent → Session、beta 头、阅读路线图与常见坑managed-agents-core.md——Agent 版本化、会话生命周期、agent_with_overrides与 mid-session 更新managed-agents-events.md——事件类型全表、live previews、断流重连合并模式managed-agents-client-patterns.md——tool_confirmation往返、自定义工具保持密钥在宿主侧等 9 个客户端模式managed-agents-environments.md——网络策略、文件/仓库挂载、会话输出双向文件桥managed-agents-self-hosted-sandboxes.md——自托管沙箱的 worker 模式与 cloud 对照python/managed-agents/README.md——Python 侧可直接运行的全流程示例赞分享人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载相关推荐RikkaHub 智能体技能库使用 Python SDK 开发 Claude Managed Agents 完整实战指南RikkaHub 智能体技能库使用 Python SDK 开发 Claude Managed Agents 完整实战指南 本文是 RikkaHub 开源仓库中人工智能大模型AI 应用移动开发交互助手Sentry 定时分诊自动化实战Claude Managed Agents 的 cron 部署与 Vault 凭据安全模型Sentry 定时分诊自动化实战Claude Managed Agents 的 cron 部署与 Vault 凭据安全模型 本文以本仓库 managed_ag示例工程将 Claude Managed Agents 封装为 MCP 服务器CMA-MCP 双端部署与实战配置指南将 Claude Managed Agents 封装为 MCP 服务器CMA MCP 双端部署与实战配置指南 本文以 managed_agents/cma m示例工程上一篇Cent AI助手使用教程智能账单分析与预算建议实战下一篇高效提示词管理sd-webui-prompt-all-in-one历史记录与收藏功能深度使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考