★ FEATURED ARTICLE 很多刚接触 Agent 开发的读者容易把“智能体”理解成一个非常简单的等式模型 工具 while 循环。只要模型能识别用户意图、能调用工具、能根据工具结果继续生成就算做出了一个 Agent。这个理解没有错但只停留在“能跑”的阶段。真正让 Agent 进入生产环境的难点从来不是写出那个循环而是“如何管理它”谁来调用它、允许它碰哪些工具、怎么防止它无限循环、出了问题怎么回溯、换了模型之后怎么灰度切换、团队里其他人能不能复用同一个 Agent。这些问题如果完全靠开发者自己写代码解决成本会非常高而且每个项目都要重复造轮子。Claude 平台上正在被广泛讨论的“Managed Agents”托管智能体解决的问题恰恰是这一层。它把 Agent 从“散落在代码里的临时逻辑”升级成“有身份、有边界、有观测、可复用、可治理的工程实体”。这篇文章会从概念、原理、环境准备、代码示例、验证方法、排错清单和工程建议几个角度把“托管智能体”这件事拆开讲清楚。读完你至少能回答三个问题托管 Agent 和普通 Agent 到底差在哪Claude 平台上应该从哪里落地托管 Agent以及一个真正可管理的 Agent 应该怎么设计、怎么验证、怎么安全上线。1. 这篇文章真正要解决的问题先看一个常见场景你写了一个能查订单状态并自动回复客户的 Agent 脚本。脚本在自己的电脑上跑得很好但到了团队协作阶段问题开始出现。第一类问题是身份和权限。脚本里的 API Key 用的是同一个账号所有 Agent 共用一套权限。你很难限制“写周报的 Agent 不能删数据库”或者“客服 Agent 只能读订单表”。一旦某个 Agent 的工具权限过宽一个小 bug 就可能造成线上事故。第二类问题是状态和资源边界。无人值守的 Agent 很容易陷入“无限重试”。比如查询接口超时它就反复调用费用在涨日志却只显示一行错误。你没有一个统一的地方设置“最多调用多少次工具、最多推理多少步、预算超过多少就熔断”。第三类问题是可观测性。自建 Agent 的日志通常是“这里 print 一下那里写个文件”。等出了问题时你连“模型在这一步看到了什么、为什么下一步调了那个工具”都不知道。排查问题全靠猜。第四类问题是复用和迭代。Agent 的逻辑封装在某个函数里换一个项目就得复制粘贴。团队里其他人不知道有这个 Agent也不知道它的能力边界于是各自实现一遍接口风格还不统一。托管智能体解决的就是这四类问题。它不是让“模型”变得更强而是给 Agent 加了一层管理面运行有位权限可控过程可查成本可管资产可复用。简单说普通 Agent 解决“能不能跑”托管 Agent 解决“能不能长期稳定地跑”。如果你正在做 Agent 产品、想把 Agent 接入公司的业务系统或者在 Claude 平台上研究 Agent 的工程化落地这篇文章适合你。2. 基础概念与核心原理2.1 什么是 AgentAgent 指的是“在循环中自主决策的模型程序”模型收到任务后不是一次性生成答案而是判断“要不要调用工具”拿到工具结果后再继续推理直到任务完成或达到终止条件。这里和普通“函数调用”的区别很关键。函数调用Function Calling只是模型输出一个“该调用哪个函数”的结构化结果下一次请求仍然由外部代码发起。而 Agent 是在一个循环里连续做多步决策模型会自己承担“下一步做什么”的责任。一个最小的 Agent 循环包括四步将用户任务和可用的工具描述交给模型。模型返回文本或者返回工具调用请求。外部代码执行对应工具把结果写回消息历史。带着工具结果继续走第 1 步直到模型认为任务结束。2.2 什么是 Managed AgentManaged Agent 可以理解为“由平台托管运行的 Agent”。托管意味着平台替你承担了 Agent 运行时的管理工作而开发者只需要声明“这个 Agent 的目标是什么、能用哪些工具、最多跑几步、需要谁审批”。用一个类比来讲自建 Agent 就像自己租一台服务器、手动部署脚本、自己盯着监控托管 Agent 就像使用云平台提供的“定时任务 权限中心 日志系统”你只需要告诉平台跑什么、怎么跑平台负责把任务隔离、日志、配额、告警都处理好。托管并不等于模型自动变成了更强的人工智能。它强调的是“运行治理能力”的托管包括四个方面运行边界最大步数、最大 token、超时时间。权限边界允许调用哪些工具禁止哪些操作。上下文管理会话记忆如何保存、如何裁剪、如何隔离。可观测性调用链、token 消耗、成本统计、审计日志。2.3 Managed Agent、Workflow 与 Subagent 的区别Workflow、Agent、Subagent和Managed Agent这四个词经常混用建议先分清边界。概念核心特征举例Workflow固定步骤由代码编排路径确定先拉取数据再调用模型总结最后写入数据库Agent动态决策模型自己决定下一步根据用户问题决定先查文档还是先运行测试Subagent被另一个 Agent 调用的子任务执行单元主 Agent 把“搜索代码”交给专门的搜索子 AgentManaged Agent带有管理面能力的 Agent 资产有独立权限、配额、日志的 Agent 服务Subagent 是“分层协作”里的执行单元Main Agent 负责拆解任务Subagent 负责聚焦某个子任务。Managed Agent 是一种“管理形态”强调这个 Agent 是独立注册、授权和观测的。两者并不冲突一个平台上托管的 Subagent往往就是实际落地形式。2.4 Claude 平台上的托管能力在 Claude 平台上Agent 的托管能力有几种常见落地形态。一是通过 Agent SDK 在代码中创建和管理 Agent适合需要深度集成自有系统的团队二是通过 Claude Code 的 agents 目录直接定义可复用的子智能体适合本地开发、自动化任务和 CLI 场景三是通过团队配置和资产管理把 Agent 的提示词、工具、权限集中维护。不同版本的具体叫法和入口可能变化但核心思路是一致的Agent 的定义应该和调用逻辑分离Agent 的权限应该最小化Agent 的运行过程应该有日志和配额。3. 环境准备与前置条件在动手之前先把环境准备好。这里不绑定太具体的版本因为 Claude 平台的产品形态更新较快特定的字段名和入口请以官方文档和实际控制台为准。3.1 准备账号与密钥使用 Claude API 或 Agent SDK 之前需要注册 Anthropic 控制台账号并创建 API Key。密钥属于敏感信息不要提交到代码仓库也不要在日志里打印。建议在项目根目录创建.env文件ANTHROPIC_API_KEY你的密钥 CLAUDE_MODEL你的模型ID在代码中通过环境变量读取不要硬编码import os api_key os.environ.get(ANTHROPIC_API_KEY) model os.environ.get(CLAUDE_MODEL)3.2 安装运行环境Python 示例建议使用虚拟环境python -m venv .venv source .venv/bin/activate # Windows 下为 .venv\Scripts\activate pip install anthropic如果你要使用 Agent SDK还需要按官方文档安装对应的 SDK 包并准备 Node.js 或使用 CLI 方式运行。安装完成后先做一个最简单的连通性测试不要让密钥问题干扰后续排查。3.3 确定 Agent 的最小边界在写任何代码之前先用纸面方式定义清楚几个问题这个 Agent 的唯一职责是什么比如“只做订单状态查询”而不是“处理所有客户问题”。它允许调用哪些工具每个工具的参数是否有限制它最多可以推理多少步超过之后怎么办哪些操作必须人工确认它的输入输出格式是什么这一步很多人会跳过但托管 Agent 的“托管”价值首先取决于你能否清楚地声明边界。边界不清晰平台即使有权限系统也无法帮你规避风险。4. 核心流程拆解从普通调用到托管 Agent4.1 先判断任务是否适合 Agent不是所有任务都要做成 Agent。如果业务规则完全固定用 Workflow 更合适如果每一步都需要模型动态判断才适合引入 Agent。判断方法很简单列出任务的分支数量和异常情况。分支少、路径固定的用 Workflow分支多、需要临场决策的用 Agent。4.2 把工具调用改造成白名单机制Agent 最大的风险来自工具权限。一个稳妥的做法是定义一张允许调用清单凡是清单之外的工具即使模型“想调用”也不允许执行。在 Claude 平台的工具配置里这也是同样的思路。工具白名单应该尽可能细。4.3 先做最小模型验证不要让 Agent 刚创建就去处理最复杂的问题。先挑一个任务用最少的工具跑通一遍能正确调用、能返回结果、能终止循环。这里的最小验证是整个托管 Agent 工程的地基。4.4 再迁移到托管配置当最小验证通过后再把提示词、工具定义和限制条件从代码中抽离出来转成独立的 Agent 定义。代码里只保留“调用哪个 Agent、传入什么参数”业务细节不再散落在各处。这是从“脚本”走向“托管”的关键一步。4.5 接入日志和监控托管环境中要确保每次 Agent 执行都能看到完整输入输出。不要只记录最终结果还要记录中间每一步模型调用次数、工具调用参数、工具返回结果、耗时和 token 消耗。4.6 灰度上线与持续迭代Agent 不是一个“写完就完”的静态代码它的行为会随模型版本、提示词、工具返回变化。上线时要预留灰度能力比如先让 5% 的流量使用新 Agent确认指标正常后再放量。迭代时每次修改提示词或工具都应该对应一个可回退版本。5. 完整示例与代码实现下面用四个示例把“最小 Agent 循环”和“托管 Agent 定义”串起来。第一个示例是完整可运行的 Python 代码演示 Agent 循环和工具结果回溯。后面几个示例演示如何把一个 Agent 定义成可复用、可管理的资产。5.1 Python 实现最小托管式 Agent 循环文件路径managed_agent_demo.pyimport os from anthropic import Anthropic client Anthropic() MODEL os.getenv(CLAUDE_MODEL, 请替换为你的模型ID) SYSTEM_PROMPT 你是一个订单查询Agent。 你的任务是根据用户提供的订单号查询订单状态并给出简要回复。 规则 1. 如果缺少订单号主动向用户索要。 2. 只能使用 search_order 工具查询订单。 3. 查询完成后用一句话总结订单状态不要编造信息。 TOOLS [ { name: search_order, description: 根据订单号查询订单状态, input_schema: { type: object, properties: { order_id: { type: string, description: 订单号例如 OX-1001 } }, required: [order_id] } } ] def call_tool(name: str, args: dict): 实际工具调用。生产环境应接入真实订单系统。 if name search_order: order_id args.get(order_id) # 这里仅做演示真实场景请查询业务数据库或接口 return {order_id: order_id, status: shipped, team: fulfillment} raise ValueError(f未知工具: {name}) def run_agent(user_message: str, max_steps: int 5): messages [ {role: user, content: user_message} ] step 0 while step max_steps: response client.messages.create( modelMODEL, systemSYSTEM_PROMPT, max_tokens1024, messagesmessages, toolsTOOLS, ) stop_reason response.stop_reason print(fstep{step 1}, stop_reason{stop_reason}) if stop_reason tool_use: # 将模型的 assistant 回复加入历史 messages.append({role: assistant, content: response.content}) for block in response.content: if block.type tool_use: tool_result call_tool(block.name, block.input) messages.append( { role: user, content: [ { type: tool_result, tool_use_id: block.id, content: str(tool_result), } ], } ) else: # 模型没有继续调用工具视为 Agent 结束 text .join(b.text for b in response.content if b.type text) print(text) return text step 1 raise RuntimeError(fAgent 超过最大步数 {max_steps}已终止执行) if __name__ __main__: run_agent(帮我查一下订单 OX-1001 的状态)这段代码的关键点在于while循环以stop_reason作为结束条件而不是简单判断返回文本。每轮工具调用后工具结果以tool_result块追加到消息历史模型才能看到真实结果。max_steps是托管式 Agent 最常见的安全约束。没有步数限制的 Agent在线环境里非常危险。运行命令export ANTHROPIC_API_KEY你的密钥 export CLAUDE_MODEL你的模型ID python managed_agent_demo.py5.2 用 Markdown 定义托管子智能体在 Claude Code 的 agents 目录中一个托管子智能体可以是一个带元信息的 Markdown 文件。这种形式的好处是提示词、工具、模型、描述集中在一个文件里团队可以像维护文档一样维护 Agent。文件路径.claude/agents/bug-triage.md--- name: bug-triage description: 对新上报的 Bug 进行初筛和分级适合研发团队使用 model: claude-sonnet-4-5 tools: - Read - Grep - Bash --- 你是一名资深的 QA 工程师负责对 Bug 做第一轮筛选。 你的任务 1. 阅读 Bug 描述提取复现步骤。 2. 搜索相关代码和日志定位可能原因。 3. 输出 Bug 等级P0 / P1 / P2。 你的约束 - 只能读取与 Bug 相关的仓库文件。 - 允许运行测试命令禁止修改配置文件。 - 如果没有把握不要下结论标注“需要人工确认”。name是 Agent 的唯一标识description是模型或其他 Agent 判断“什么时候该用它”的依据tools是允许工具的白名单。这里的关键经验是description要写清楚适用场景否则主 Agent 遇到任务时不知道应该选它。5.3 通过 Agent SDK 调用托管智能体文件路径run_managed_agent.ts下面的代码是结构示例具体构造参数以你安装的 Agent SDK 文档为准。import { runAgent } from claude-agent-sdk; const result await runAgent({ name: bug-triage, prompt: 请检查订单服务最近一次线上报障输出 P0/P1 分级, tools: [Read, Grep, Bash], maxSteps: 5, model: claude-sonnet-4-5, }); console.log(result.text); console.log(token usage:, result.usage);这段代码代表一个很重要的切换你在业务代码里不再手工拼系统提示词而是通过名称引用一个已经定义好的托管智能体。业务代码只关心“哪个 Agent、什么任务”Agent 的内部规则全部收敛到定义文件中。5.4 维护团队级 Agent 清单当 Agent 数量变多后建议维护一份统一清单方便团队审查和控制权限。下面是一个 JSON 结构示意字段可以按团队需要调整文件路径agents.manifest.json{ agents: [ { name: bug-triage, path: .claude/agents/bug-triage.md, owner: release-team, allowed_input: [issue description or order id], max_steps: 5, requires_approval: [Bash] }, { name: order-query, path: .claude/agents/order-query.md, owner: customer-service, allowed_input: [order id], max_steps: 3, requires_approval: [] } ] }这份清单的作用不是给平台看的而是给团队做“变更评审”和“权限审计”用的。每次新加 Agent、扩大工具权限、提高步数限制都可以经过代码评审流程避免一个人在本地静默上线一个高权限 Agent。6. 运行结果与效果验证6.1 预期输出运行 5.1 节示例时正常情况下应该看到类似输出step1, stop_reasontool_use step2, stop_reasonend_turn 订单 OX-1001 的状态是 shipped当前由 fulfillment 团队处理。第一轮模型判断需要调用工具第二轮拿到工具结果后生成最终答复。这个模式证明 Agent 循环是通的。6.2 验证点清单不要只看到“输出了结果”就认为成功。托管 Agent 上线前建议逐项检查模型是否正确选择了工具而不是自己编造结果。工具返回后模型是否使用了真实返回值。步数限制是否生效把工具改成永远报错确认 Agent 会在max_steps后停止。上下文是否正常连续多轮后没有丢失订单号等关键信息。成本是否可估算一次完整任务消耗了多少 token。异常路径是否可回滚调用了错误工具后系统是否能安全恢复。6.3 失败时先看哪里如果运行失败先不要急着换模型或改提示词。按顺序排查看密钥和模型 ID 是否正确先跑一个最简单的“无工具调用”请求。看工具描述和参数命名模型经常因为input_schema不清晰而传错参数。看消息历史格式tool_result必须放到 user 消息里且带tool_use_id。看是否触发步数上限如果反复卡在工具调用可能是工具返回不够明确。7. 常见问题与排查思路下面表格整理了托管 Agent 落地过程中最高频的问题。遇到问题时先对照问题现象再按排查思路走不要一上来就重写代码。问题现象可能原因排查方式解决方案Agent 从头到尾不调用工具工具描述不清晰模型认为不需要工具查看第一轮模型输出和日志重写工具描述加入“什么情况下必须调用”工具调用时参数总是缺字段input_schema 描述不够明确检查模型传入的 JSON 参数给必填字段加示例值并在描述中说明格式Agent 在工具调用后反复循环工具返回结果没有反映到消息历史检查tool_result是否正确写回确保每轮把工具结果追加为 user 消息运行报超出步数工具结果不足以让模型结束查看中间日志确认最后一次工具返回增加步数上限同时优化工具返回信息单个 Agent 回答不稳定提示词对输出格式约束不足对比多次测试记录在提示词中增加可被验证的输出结构成本突然升高没有设置步数或 token 限制查看 token 使用明细设置 max_steps、max_tokens 和熔断策略Agent 访问到不该访问的资源工具白名单过宽审查 Agent 的工具配置最小化工具清单敏感操作增加人工审批多个 Agent 互相抢着处理同一任务description 边界不清晰检查各 Agent 的 description细化每个 Agent 的适用场景和排除场景8. 最佳实践与工程建议8.1 每个 Agent 只做一件足够小的事托管智能体最忌讳“万能 Agent”。如果你发现提示词里写了十几个“你还可以做”说明边界已经失控。更好的做法是拆成多个专业 Agent由主 Agent 或上层调度器按任务决定调用哪一个。每个 Agent 的职责越小提示词越稳定权限也越容易控制。8.2 把权限设计当成第一优先级在 Claude 平台配置 Agent 时工具列表不要贪多。能读文件就不要给写权限能用 Git 命令就不要给删除远程分支的权限。对任何可能改变线上状态的工具都应增加人工审批环节。托管平台提供的权限能力只有在你把工具清单收敛到最小范围时才能真正生效。8.3 描述信息要面向模型写Agent 的description不只是给人看的更是给主 Agent 或平台选择器看的。避免写空泛的“负责处理各类问题”要写成“当用户在查询订单状态时使用本 Agent当用户要求修改订单时不要使用本 Agent”。带排除条件的描述能显著减少错误路由。8.4 上下文管理要显式设计Agent 的记忆不是“把每一轮对话都塞进去”。长期记忆要写入独立存储短期记忆只保留任务相关上下文。在托管 Agent 中要理解平台对上下文的处理方式避免无限制追加历史导致 token 膨胀。上下文越长模型越容易丢失早期指令。8.5 日志必须保留完整决策链托管 Agent 的日志应该至少包含输入任务、模型每一步的思考摘要、模型返回的文本、工具调用参数、工具执行结果、耗时和 token 消耗。日志不是给人实时读的而是用于事后复盘。没有完整决策链遇到线上事故就只能靠猜测。8.6 每次修改都要可回滚Agent 的提示词和工具配置本质上是“可部署的资产”。每次变更都应有版本记录。上生产环境前先在测试环境用固定用例回归再灰度放量。不要为了赶进度直接让全量流量使用未验证的新 Agent。8.7 成本与熔断给 Agent 设置明确的成本上限并配置熔断规则。例如单次执行超过 5 步或消耗超过预设 token直接终止并告警。在无人值守场景下Agent 的自主性越强熔断机制就越重要。9. 总结与后续学习方向回到开头的问题Managed Agents 解决的不是“模型能不能推理”而是“Agent 能不能被工程化地使用”。在 Claude 平台上托管智能体的价值体现在四层第一层是把 Agent 定义成独立资产让提示词和代码分离第二层是把工具权限和运行边界固化下来让 Agent 只能做被允许的事第三层是把日志和成本透明化让每次执行都可追踪第四层是让团队可以像评审代码一样评审 Agent 的变更。如果你想继续深入学习建议按这个路径实践先跑通一个最小工具循环再把 Agent 定义改成独立文件接着把工具的权限白名单机制引入简单模拟“越权调用被拒绝”的场景最后把日志、步数限制和成本统计补上把一个演示脚本改造成可以接受灰度流量的托管 Agent。下一步可以继续研究 Subagent 的任务拆分、Skills 的能力封装以及如何用真实的业务工具替换示例中的模拟逻辑。建议你把文中的最小示例保存下来先跑通再逐步扩展。托管 Agent 的坑都在细节里早踩早改。
阅读完成 · 觉得有帮助？
