1. 这不是新赛道是 runtime 层的“操作系统时刻”来了我第一次在生产环境里跑一个需要连续调用七次外部 API、中间还要做三次人工审核确认的客服工单处理 agent是在 2025 年初。当时我们没用任何托管 runtime全靠自己搭的 Flask Redis Docker Compose 小集群撑着。系统上线第三天凌晨两点监控告警炸了Redis 内存使用率 98%但实际缓存数据量只有设计容量的 30%。排查了六个小时最后发现是 session state 全堆在 Redis 的一个 hash key 里而每次 agent 调用工具后我们习惯性地把整个 conversation history含所有 tool call 输入输出、中间思考链、用户原始消息一股脑 append 进去——不是序列化成结构化日志而是拼成一个超长字符串。更糟的是这个字符串还被反复读取、截断、再拼接导致 Redis 内存碎片率飙升。那晚我们手动 kill 掉了所有卡死的 session重置了 Redis然后坐在会议室里盯着白板上画歪的架构图发呆为什么我们非得让大模型的 context window 承担状态存储的职责它明明是个计算单元不是数据库。Anthropic 在 4 月 8 日发布的 Claude Managed Agents表面看是一套带 sandbox 和 credential vault 的托管 agent 运行时但真正击中行业痛点的是它把“session”从一个模糊的、依附于模型上下文的临时概念变成了一个独立、持久、可查询、可回溯的事件日志event log。这不是功能叠加是范式迁移。它和 AWS Bedrock AgentCore、Google Vertex AI Agent Builder、Microsoft Azure AI Foundry 一起共同指向一个事实agent runtime 这一层正在快速变成基础设施的“操作系统层”——它必须稳定、抽象、解耦然后被压缩。关键词“Towards AI - Medium”背后是大量一线工程师在真实场景中踩出的坑、熬过的夜、写废的代码。这篇文章不讲 hype不炒概念只拆解这个“操作系统层”到底长什么样为什么它注定要走向 commoditization商品化以及当它变薄、变透明、甚至“归零”时你手里的筹码究竟该押在哪一层。这东西适合谁如果你正用 LangChain 或 LlamaIndex 自己搭 agent发现调试时总得翻十页日志才能定位到某次失败的 Slack webhook如果你的团队在纠结要不要自建 sandbox 集群还是直接上云厂商的托管服务如果你的老板问“我们花这么多钱买 Claude token凭什么还要额外付 runtime 费用”那你就是这篇内容最该读的人。它不教你怎么写 prompt也不讲 RAG 的 embedding 选型它讲的是当你的 agent 开始承担真实业务流比如自动处理客户退款、生成合规财务报告、实时分析销售通话录音支撑它的底层 runtime其设计哲学、技术选型、成本结构将直接决定你项目的生命周期是三个月还是三年。2. 核心设计与思路拆解为什么“Session as Event Log”是唯一正确的起点2.1 剥离 hype看清本质Managed Agents 是什么不是什么先划清边界。Anthropic Managed Agents 不是不是一个新模型它不改变 Claude 模型本身的能力、推理速度或 token 成本。你支付的仍然是标准的 input/output token 费用外加 runtime 的 session-hour 费用。不是一个低代码拖拽平台它没有图形化工作流编辑器不提供“点击添加 Slack 集成”这种傻瓜式操作。你定义 agent 的方式要么是 YAML 文件声明式要么是自然语言描述如 “You are a customer support agent for Acme Corp. You can access the CRM via the ‘get_customer’ tool and update tickets via ‘update_ticket’…”但最终执行逻辑、工具调用顺序、错误处理策略仍需由开发者通过代码或配置明确表达。不是一个端到端的 SaaS 应用它不直接面向最终用户如客服代表而是面向开发者和工程团队。Notion 用它来构建内部团队协作 agentRakuten 用它来搭建跨部门的销售/营销/财务 agent这些都不是开箱即用的成品而是嵌入到现有工作流中的定制化能力模块。它真正是什么是一个高度工程化的、托管的、安全沙箱化的 agent 执行环境hosted runtime environment。它的核心价值在于将 agent 运行时的三大关键责任从开发者肩上彻底卸下并交由一个经过大规模验证的、企业级的基础设施来承担State Management状态管理Session 数据的持久化、版本控制、查询与回溯。Execution Isolation执行隔离工具调用的安全沙箱、资源配额、凭据保密。Observability可观测性完整的、结构化的、可审计的执行轨迹记录。这三点恰恰是绝大多数自研 agent 系统在规模扩大后最先崩溃的地方。我们团队当年那个凌晨两点的 Redis 崩溃根源就在第一点——我们试图用一个为高速缓存设计的系统去承担一个为持久化日志设计的职责。这是典型的“错位使用”。2.2 “Session as Event Log”一场静默的革命Anthropic 工程博客里反复强调的 “session as durable event log living outside the model context”这句话的分量远超其字面意思。让我用一个具体场景来还原它解决的“静默崩溃”问题。假设你有一个处理保险理赔的 agent流程是用户上传事故照片和医疗报告 PDFagent 调用 OCR 工具提取文本agent 调用 NLP 工具分析伤情严重程度agent 调用规则引擎判断是否符合快速赔付条件如果符合调用支付网关发起打款如果不符合调用邮件服务发送拒赔说明。这个流程可能耗时 15-45 分钟。在传统基于 context window 的实现中每一步的输入、输出、中间思考“这张照片显示左臂有明显肿胀结合病历描述初步判断为骨折”都会被追加到一个不断增长的 message 数组里作为下一次 LLM 调用的messages参数。当这个数组长度逼近 Claude 3.5 Sonnet 的 200K token 上限时会发生什么不是优雅降级LLM 不会主动告诉你“context 即将满请清理历史”。它会默默地、毫无征兆地开始丢弃最早的消息。你可能在第 4 步还能看到清晰的 OCR 结果到了第 5 步LLM 的思考链里就只剩“用户上传了文件…需要判断赔付…”而关键的 OCR 文本和 NLP 分析结果已经从它的“记忆”里蒸发了。后果是灾难性的它可能基于一个残缺的、错误的历史做出完全错误的决策。比如因为看不到“伤情为骨折”的结论它误判为轻伤触发了快速赔付流程导致公司损失一笔不该付的钱。更可怕的是你无法复现、无法调试、无法审计。当你事后想查“为什么 agent 给了赔付”你只能看到最后几轮的对话而最关键的前几步证据已经随着 context 的滚动而永远丢失。Managed Agents 的解决方案是物理性地切断这个链条。Session 不再是 LLM 的“记忆”而是一个独立的、时间戳有序的、不可变的事件流immutable event stream。每一次 tool call 的请求、响应、元数据耗时、返回码、sandbox ID每一次 LLM 的输出包括其内部的 reasoning trace都被作为一个独立的、结构化的 event写入一个专用的、高可用的日志存储很可能是基于对象存储索引服务的组合。LLM 的 context window只负责承载当前这一轮推理所需的最小信息集例如当前任务目标、最新一条用户消息、上一轮 tool call 的简要结果摘要。状态的“真相”永远在 event log 里。提示这个设计带来的最大好处是“可确定性”determinism。你可以随时awake(sessionId)让一个挂起的 session 从任意一个已知的 event 点恢复执行而无需担心 context 的完整性。这为 long-running, human-in-the-loop 的复杂工作流提供了坚实基础。2.3 Credential Isolation生产环境的“最后一道防火墙”另一个常被低估但在生产环境中生死攸关的设计是凭据credentials的隔离。在我们早期的自研系统中为了方便我们曾把 API Key 直接作为环境变量注入到运行 agent 的 Docker 容器里。这带来了两个致命风险LLM 的“越狱”风险如果 agent 的 system prompt 或用户输入存在诱导性LLM 可能生成一段包含curl -H Authorization: Bearer your_api_key ...的代码并尝试在 sandbox 中执行。虽然 sandbox 本身是隔离的但如果凭据以明文形式存在于其环境变量中一旦 sandbox 存在未被发现的逃逸漏洞凭据就暴露了。审计与合规黑洞当安全团队要求你证明“谁在何时调用了哪个 API”你无法提供精确的、与具体 tool call 绑定的凭据使用记录。你只能证明“这个容器启动时拥有这个 Key”但无法证明 Key 是否被滥用。Managed Agents 的做法是“凭据即服务”Credentials-as-a-Service。你在 Anthropic 控制台中将各类 API Key、OAuth tokens、数据库连接串等安全地存储在他们的 Vault 中。当你在 agent 的 YAML 定义里声明一个 tool如send_slack_message你只需指定该 tool 所需的凭据类型如slack_bot_token。在 runtime当 agent 发起 tool call 时Harness执行器会向 Vault 申请一个短期、作用域受限、一次性的访问令牌short-lived, scoped, one-time-use token并将其注入到 sandbox 的执行环境中。这个令牌在本次调用结束后立即失效且其权限被严格限制在本次调用所需的最小范围内例如只能向特定 channel 发送消息不能读取历史。这不仅仅是安全加固它是一种架构上的信任委托。它意味着你不再需要信任 LLM 不会“偷看”你的环境变量你只需要信任 Anthropic 的 Vault 服务和 sandbox 的隔离机制——这两者都是经过严格审计和大规模验证的成熟组件。对于金融、医疗等强监管行业这种设计几乎是进入生产环境的强制性门槛。3. 核心细节解析与实操要点YAML 定义、Sandbox 行为与定价模型3.1 定义一个 AgentYAML 是你的“源代码”Managed Agents 的核心配置是一个 YAML 文件。这并非简单的参数列表而是一个完整的、声明式的 agent “蓝图”。让我们拆解一个生产级的、用于处理 GitHub Issue 的 agent 示例# github-issue-agent.yaml name: github-issue-resolver description: An agent that triages, investigates, and proposes fixes for GitHub issues. version: 1.2.0 # System Prompt: 这是 agent 的“人格”和“宪法” system_prompt: | You are an expert software engineer at Acme Corp, responsible for maintaining the acme-web repository. Your primary goal is to understand the users issue, reproduce it if possible, identify the root cause, and propose a concrete fix in the form of a pull request description and code diff. You MUST follow these rules: - Never assume code exists; always use the list_files and read_file tools first. - If you cannot reproduce the issue after 3 attempts, ask the user for more details or a minimal reproduction case. - Always cite the exact line numbers and file paths from your investigation. # Tools: 这是 agent 的“手脚”定义了它能做什么 tools: - name: list_files description: List all files in the specified directory of the repository. input_schema: type: object properties: path: type: string description: The directory path to list (e.g., src/components/). # 凭据绑定此 tool 使用 github_read_token credentials: github_read_token - name: read_file description: Read the contents of a specific file. input_schema: type: object properties: file_path: type: string description: The full path to the file (e.g., src/components/Button.tsx). credentials: github_read_token - name: search_code description: Search for a specific string across the entire codebase. input_schema: type: object properties: query: type: string description: The string to search for. credentials: github_read_token - name: create_pull_request description: Create a new pull request with a title, description, and proposed code changes. input_schema: type: object properties: title: type: string description: The title of the PR. description: type: string description: A detailed description of the fix and the problem it solves. base_branch: type: string default: main description: The branch to merge into. head_branch: type: string description: The new branch to create for this PR. file_changes: type: array items: type: object properties: file_path: type: string content: type: string operation: type: string enum: [create, update, delete] credentials: github_write_token # 注意此 tool 使用更高权限的 token # Guardrails: 这是 agent 的“刹车”和“护栏” guardrails: # 防止无限循环 max_tool_calls_per_session: 50 # 防止过度消耗 token max_tokens_per_call: 8192 # 防止访问敏感路径 blocked_paths: - /etc/** - /root/** - secrets/** # 强制内容安全检查 content_moderation: enabled: true policies: - hate_speech - self_harm - violence # Runtime Configuration: 这是 agent 的“硬件规格” runtime: # Sandbox 的 CPU 和内存配额 cpu: 2vCPU memory: 4GB # Session 的最大存活时间超过此时间session 自动终止 max_session_duration_hours: 8 # Sandbox 的最大执行时间单次 tool call 的超时 max_sandbox_execution_seconds: 120这个 YAML 文件就是你交付给 Anthropic 的“源代码”。它包含了 agent 的全部灵魂它知道什么system_prompt、它能做什么tools、它不能做什么guardrails、以及它有多大的力气runtime。关键在于所有这些配置都与具体的 LLM 实例解耦。你可以今天用 Claude 3.5 Sonnet明天无缝切换到 Claude 3.7 Opus只要它们的 API 接口兼容agent 的行为逻辑就不会改变。这就是“稳定抽象”的力量。3.2 SandboxCattle, Not PetsAnthropic 工程博客里那句 “Sandboxes as cattle, not pets”是理解其执行模型的关键。在传统运维中“pets” 是指那些被精心照料、有名字、有 IP、出了问题要连夜抢救的服务器而 “cattle” 是指那些编号管理、批量部署、坏了就立刻替换的虚拟机。Managed Agents 的 sandbox就是彻头彻尾的 “cattle”。按需创建用完即焚每次 agent 需要执行一个 tool call比如运行一个 Python 脚本来调用 GitHub APIHarness 就会从一个预热好的 sandbox 池中分配一个干净的、隔离的实例。这个实例在 tool call 执行完毕、返回结果后就会被立即销毁。它不会保留任何状态也不会被复用。资源硬隔离每个 sandbox 都有严格的 CPU、内存、网络带宽和磁盘 I/O 配额。一个失控的、写死循环的 Python 脚本最多只能耗尽它自己的 2vCPU 和 4GB 内存绝不会影响到同一物理主机上运行的其他 sandbox。网络策略白名单sandbox 默认是网络隔离的。它只能访问你明确允许的外部服务如api.github.com,slack.com并且只能使用你为其配置的、经过 Vault 签发的凭据。它无法访问内网数据库也无法进行 DNS 查询去探测内部网络拓扑。这种设计直接消除了“共享宿主机”模式下的所有安全隐患和性能抖动。你不需要担心一个 buggy 的 agent 会拖垮整个集群也不需要为每个 agent 单独配置复杂的防火墙规则。它就像一个一次性的、高度受控的实验室只为你当前的实验tool call服务。3.3 定价模型$0.08/session-hour 的深意Managed Agents 的定价是$0.08 per session-hour of active runtime外加标准的 Claude token 费用。这个看似简单的数字背后有深刻的工程和商业逻辑。首先明确什么是 “session-hour”它不是指 agent 被创建的总时长而是指session 处于“活跃”active状态的时间总和。一个 session 的生命周期是从第一个用户消息触发 agent 启动到 session 最终完成成功或失败并被关闭。在这期间如果 agent 因为等待用户输入、等待外部 API 响应、或执行一个长时间运行的 tool如视频转码而处于空闲idle状态这段时间不计入session-hour。只有当 Harness 正在执行 LLM 推理、或者 sandbox 正在执行 tool call 时计时器才开始走。这意味着一个处理简单问答的 session可能只消耗几秒钟的 session-hour而一个需要多次迭代、等待人工审核、再继续执行的复杂工作流其 session-hour 会累积得更多。$0.08 这个价格是经过精密计算的对标云厂商的 IaaS 成本AWS EC2 t3.medium 实例2vCPU, 4GB RAM的按需价格约为 $0.0416/hour。Anthropic 的 $0.08大致相当于在其之上叠加了 sandbox 隔离、Vault 凭据服务、event log 存储与索引、以及高级 guardrails 的成本。这是一个有利润但不过分溢价的定价旨在吸引开发者从自建方案迁移过来。小规模友好大规模有压力对于一个初创团队每月处理 1000 个平均时长 5 分钟的 sessionsession-hour 成本仅为 $0.08 * (1000 * 5 / 60) ≈ $6.67完全可以忽略。但对于一个大型企业每天处理 10 万个 session其中很多是复杂的、耗时的流程这笔费用就会迅速攀升到数万美元/月。这正是 Anthropic 的商业意图用一个合理的价格把你“锁”在 Claude 生态里让你的 token 花费成为主要成本而 runtime 成本则成为一个温和但持续的“粘性”收入。注意这个定价模型也暗示了最佳实践——尽可能优化 agent 的 workflow减少不必要的 tool calls 和 LLM 推理轮次。一个设计精良的 agent应该能在 3-5 轮内完成任务而不是陷入无休止的“思考-调用-再思考”循环。这既是成本考量也是用户体验的底线。4. 实操过程与核心环节实现从本地开发到生产部署的完整链路4.1 本地开发与测试告别“黑盒”拥抱可重现性在 Managed Agents 之前本地开发 agent 是一件痛苦的事情。你写的 YAML 或代码在本地跑得好好的一上生产环境就各种诡异问题sandbox 权限不够、凭据加载失败、网络策略拦截、甚至是因为不同版本的 Python 解释器导致的细微差异。Managed Agents 提供了一套强大的本地开发工具链其核心思想是让本地环境与生产环境尽可能一致从而消灭“在我机器上是好的”这类问题。Anthropic 提供了一个名为claude-managed-agents-cli的命令行工具。它的核心工作流如下初始化本地沙箱Local Sandbox# 创建一个与生产环境完全一致的本地 sandbox claude-managed-agents-cli sandbox init --cpu 2 --memory 4GB --network-policy ./network-policy.json这个命令会启动一个 Docker 容器模拟生产 sandbox 的所有约束CPU/Memory 配额、网络白名单network-policy.json定义了允许访问的域名和端口、以及一个模拟的 Vault 服务用于测试凭据注入。在本地沙箱中运行 Tool# 将你的 tool 代码如 github_tools.py放入 sandbox并用模拟凭据运行 claude-managed-agents-cli sandbox run --tool ./tools/github_tools.py --input {file_path: README.md} --credentials ./mock-creds/github_read_token.json这会将你的 Python 脚本在受控的 sandbox 环境中执行并返回其 stdout/stderr。你可以在这里精确地调试脚本的网络请求、文件读写、错误处理逻辑而无需担心污染本地环境。本地模拟 Session 执行# 使用你的 YAML 定义和一组测试消息模拟整个 session 流程 claude-managed-agents-cli simulate --agent ./agents/github-issue-agent.yaml --messages ./test-data/issue-123.json这个命令会启动一个本地的 Harness 模拟器。它会加载你的 YAML解析 system_prompt 和 tools。用一个轻量级的本地 LLM如 Ollama 的llama3:8b模拟 Claude 的推理过程。对于每一个 tool call它会调用你之前在 sandbox 中测试好的本地 tool。将整个执行过程包括 LLM 的输出、tool 的输入输出、耗时以结构化的 JSON 格式输出到一个trace.log文件中。这个trace.log文件就是你的本地开发“黄金标准”。它是一个完整的、可重现的、可版本控制的执行快照。你可以把它提交到 Git作为回归测试的基准。当生产环境出现异常时你只需用同样的输入消息和 YAML再次运行simulate就能 100% 复现问题而无需登录生产服务器去翻日志。4.2 生产部署与集成API 驱动的无缝嵌入Managed Agents 的生产部署完全通过 RESTful API 完成。它没有 Web 控制台的“一键部署”按钮这恰恰是其工程严谨性的体现——一切皆可编程一切皆可自动化。核心 API 流程如下注册 Agentcurl -X POST https://api.anthropic.com/v1/managed-agents \ -H x-api-key: $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d { name: github-issue-resolver, description: Triage and fix GitHub issues., config_yaml: $(cat github-issue-agent.yaml | jq -sRr uri), model: claude-3-5-sonnet-20240620 }这个 API 调用会返回一个唯一的agent_id如agnt_abc123这就是你的 agent 在 Anthropic 云上的“身份证”。启动 Sessioncurl -X POST https://api.anthropic.com/v1/managed-agents/$AGENT_ID/sessions \ -H x-api-key: $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: Issue #123: Button click doesnt trigger navigation. Heres the stack trace...} ], metadata: { source: github-webhook, issue_id: 123, repo: acme-web } }这会创建一个新的 session并返回session_id和初始的response通常是 agent 的第一轮回复。metadata字段非常重要它会被自动注入到每一个 event log 中成为你后续审计和分析的关键维度。流式获取响应与处理 Tool Calls# 使用 Server-Sent Events (SSE) 流式接收响应 curl -N https://api.anthropic.com/v1/managed-agents/$AGENT_ID/sessions/$SESSION_ID/stream \ -H x-api-key: $ANTHROPIC_API_KEY这个流会推送一系列事件{type: message, content: Ill investigate this issue...}LLM 的回复{type: tool_use, name: list_files, input: {path: src/components/}}agent 决定调用 tool{type: tool_result, name: list_files, output: [Button.tsx, Header.tsx, ...]}tool 执行结果你的应用后端需要监听这个流并对tool_use事件做出响应调用你自己的内部服务如一个封装了 GitHub API 的微服务来执行真正的逻辑然后将结果通过POST /sessions/{session_id}/tool_resultsAPI 回传给 Anthropic。这个 API 驱动的模型让你可以将 Managed Agents 无缝嵌入到任何现有的技术栈中。它可以是一个 Node.js Express 应用的中间件处理来自 Slack 的事件。一个 Python FastAPI 服务作为 GitHub Webhook 的接收器。一个 Java Spring Boot 微服务集成到你的企业 Service Mesh 中。它不强迫你重构整个应用只是提供了一个强大、可靠的“智能执行单元”。4.3 监控、告警与可观测性Event Log 是你的新“仪表盘”当你的 agent 运行在 Managed Agents 上你拥有的不再是零散的日志行而是一个结构化的、富含语义的事件数据库。这才是真正的可观测性。Anthropic 提供了/v1/managed-agents/{agent_id}/sessions/{session_id}/eventsAPI你可以用它来查询任意 session 的完整事件流。但更重要的是他们提供了基于这些 event log 的高级分析能力。假设你想回答以下问题Q1过去 24 小时内哪些 tool call 的失败率最高你可以查询所有tool_result事件按name分组统计status为error的比例。你会发现search_code的失败率高达 15%而其他 tool 都低于 1%。进一步分析tool_result事件中的error_message字段发现大部分是Rate limit exceeded。这立刻指向了 GitHub API 的配额问题你需要去调整search_codetool 的凭据使用一个更高配额的 token。Q2平均来看一个 issue 从创建到 agent 提出 PR需要多少轮 LLM 推理查询所有message事件role 为assistant按session_id分组计数。你发现中位数是 4 轮但 p95 是 12 轮。这说明有少数复杂 issue 导致了长尾延迟。你可以筛选出这些长尾 session分析它们的 event log发现它们都涉及了对read_file的多次调用进而推断出 agent 的文件搜索策略效率低下需要优化list_files和search_code的协同逻辑。Q3我们的 agent 是否在无意中访问了被禁止的路径查询所有tool_use事件检查其input字段是否匹配blocked_paths规则。如果发现有匹配这不仅是安全告警更是 prompt 工程的失败信号——你的 system_prompt 没有足够清晰地约束 agent 的行为边界。实操心得我们团队在上线后的第一周就建立了一个简单的 Grafana 仪表盘将上述三个问题的指标可视化。它成为了我们每日站会的固定议程“昨天的 top 3 问题是什么我们修复了几个” 这种基于 event log 的、数据驱动的迭代比任何主观的“我觉得 agent 还行”都要可靠得多。5. 常见问题与排查技巧实录从“Why is my tool not running?” 到 “How do I debug hallucination?”5.1 常见问题速查表问题现象可能原因排查步骤解决方案Tool call 从未被触发1. LLM 的 reasoning chain 中根本没有生成tool_useblock。2. YAML 中 tool 的input_schema与 LLM 生成的inputJSON 不匹配字段名、类型错误。1. 查看message事件检查 LLM 的完整输出特别是其内部的thinking部分。2. 查看tool_use事件如果存在对比其input与 YAML 中定义的input_schema。1. 优化 system_prompt加入更明确的指令如 “When you need to read a file, ALWAYS use theread_filetool. NEVER try to guess the file contents.”2. 在 YAML 中为input_schema添加更详细的description并确保字段名与 LLM 的常用命名习惯一致如用file_path而非path_to_file。Tool call 执行失败返回Permission denied1. Sandbox 的网络策略阻止了对目标域名的访问。2. 凭据 Vault 中的 token 已过期或权限不足。1. 检查tool_use事件中的target_url确认其是否在network-policy.json的白名单中。2. 查看tool_result事件中的error_message确认是否为401 Unauthorized或403 Forbidden。1. 更新network-policy.json并重新部署 agent。2. 登录 Anthropic 控制台检查对应凭据的配置和有效期并更新。Session 在中途“消失”没有session_ended事件1. Session 超过了max_session_duration_hours。2. Harness 进程崩溃极罕见但可能。1. 检查session_started事件的时间戳计算其是否超过了配置的最大时长。2. 查看session_events的最后一条记录确认其类型。1. 在启动 session 时增加metadata字段标记其预期用途并在应用层设置一个定时器在超时前主动调用awake或end_session。2. 联系 Anthropic 支持并提供session_id这是基础设施层面的问题。LLM 的回复中出现了明显的幻觉Hallucination1. Tool call 的结果tool_result被 LLM 错误地解读或忽略了。2. System prompt 没有强制要求 LLM 必须基于 tool 结果进行推理。1. 对比tool_use事件的input和tool_result事件的output确认 tool 返回了正确信息。2. 检查message事件中 LLM 的输出看其是否提到了 tool 的结果。1. 在 system_prompt 中加入强约束“YOU MUST BASE YOUR ENTIRE REPLY ON THE OUTPUT OF THE TOOLS. IF A TOOL RETURNS DATA, YOU MUST INCORPORATE IT EXPLICITLY IN YOUR RESPONSE. DO NOT MAKE UP INFORMATION.”2. 在 YAML 的guardrails中启用content_moderation并添加factual_consistency策略如果 Anthropic 提供。5.2 独家避坑技巧从血泪教训中提炼技巧一永远为你的 Tool 编写“防御性”包装器不要让你的 Python/Node.js tool 脚本直接暴露在 sandbox 中。一定要写一个包装器wrapper它负责输入校验检查inputJSON 是否符合预期对非法输入抛出清晰的错误如{error: Invalid file_path: must be a string starting with src/}而不是让脚本崩溃。超时控制即使 sandbox 有max_sandbox_execution_seconds你的脚本内部也应设置一个更短的 timeout如 30 秒并捕获TimeoutError返回友好的错误信息。错误标准化无论底层 API 返回什么格式的错误如 GitHub 的404 Not Found或422 Unprocessable Entity你的 wrapper 都应将其统一转换为一个标准的、易于 LLM 理解的 JSON 错误结构。为什么因为 LLM 的推理能力很大程度上依赖于它接收到的tool_result的质量和一致性。一个混乱的、格式不一的错误信息会让 LLM 陷入困惑从而产生幻觉。一个清晰、结构化的错误反而能引导 LLM 做出更合理的下一步决策如“哦文件不存在那我应该先用list_files看看有哪些文件”。技巧二Session Metadata 是你的“上帝视角”metadata字段是你在 event log 中的“锚点”。不要只把它当作一个备注。你应该系统性地填充它{source: slack, channel_id: C012AB3CD, user_id: U456EF7GH}{source: web, page_url: https://acme.com/contact, utm_campaign: q2-support}这样当你在 Grafana 里看到某个 tool 的失败率
Agent Runtime 正在成为 AI 时代的操作系统层
1. 这不是新赛道是 runtime 层的“操作系统时刻”来了我第一次在生产环境里跑一个需要连续调用七次外部 API、中间还要做三次人工审核确认的客服工单处理 agent是在 2025 年初。当时我们没用任何托管 runtime全靠自己搭的 Flask Redis Docker Compose 小集群撑着。系统上线第三天凌晨两点监控告警炸了Redis 内存使用率 98%但实际缓存数据量只有设计容量的 30%。排查了六个小时最后发现是 session state 全堆在 Redis 的一个 hash key 里而每次 agent 调用工具后我们习惯性地把整个 conversation history含所有 tool call 输入输出、中间思考链、用户原始消息一股脑 append 进去——不是序列化成结构化日志而是拼成一个超长字符串。更糟的是这个字符串还被反复读取、截断、再拼接导致 Redis 内存碎片率飙升。那晚我们手动 kill 掉了所有卡死的 session重置了 Redis然后坐在会议室里盯着白板上画歪的架构图发呆为什么我们非得让大模型的 context window 承担状态存储的职责它明明是个计算单元不是数据库。Anthropic 在 4 月 8 日发布的 Claude Managed Agents表面看是一套带 sandbox 和 credential vault 的托管 agent 运行时但真正击中行业痛点的是它把“session”从一个模糊的、依附于模型上下文的临时概念变成了一个独立、持久、可查询、可回溯的事件日志event log。这不是功能叠加是范式迁移。它和 AWS Bedrock AgentCore、Google Vertex AI Agent Builder、Microsoft Azure AI Foundry 一起共同指向一个事实agent runtime 这一层正在快速变成基础设施的“操作系统层”——它必须稳定、抽象、解耦然后被压缩。关键词“Towards AI - Medium”背后是大量一线工程师在真实场景中踩出的坑、熬过的夜、写废的代码。这篇文章不讲 hype不炒概念只拆解这个“操作系统层”到底长什么样为什么它注定要走向 commoditization商品化以及当它变薄、变透明、甚至“归零”时你手里的筹码究竟该押在哪一层。这东西适合谁如果你正用 LangChain 或 LlamaIndex 自己搭 agent发现调试时总得翻十页日志才能定位到某次失败的 Slack webhook如果你的团队在纠结要不要自建 sandbox 集群还是直接上云厂商的托管服务如果你的老板问“我们花这么多钱买 Claude token凭什么还要额外付 runtime 费用”那你就是这篇内容最该读的人。它不教你怎么写 prompt也不讲 RAG 的 embedding 选型它讲的是当你的 agent 开始承担真实业务流比如自动处理客户退款、生成合规财务报告、实时分析销售通话录音支撑它的底层 runtime其设计哲学、技术选型、成本结构将直接决定你项目的生命周期是三个月还是三年。2. 核心设计与思路拆解为什么“Session as Event Log”是唯一正确的起点2.1 剥离 hype看清本质Managed Agents 是什么不是什么先划清边界。Anthropic Managed Agents 不是不是一个新模型它不改变 Claude 模型本身的能力、推理速度或 token 成本。你支付的仍然是标准的 input/output token 费用外加 runtime 的 session-hour 费用。不是一个低代码拖拽平台它没有图形化工作流编辑器不提供“点击添加 Slack 集成”这种傻瓜式操作。你定义 agent 的方式要么是 YAML 文件声明式要么是自然语言描述如 “You are a customer support agent for Acme Corp. You can access the CRM via the ‘get_customer’ tool and update tickets via ‘update_ticket’…”但最终执行逻辑、工具调用顺序、错误处理策略仍需由开发者通过代码或配置明确表达。不是一个端到端的 SaaS 应用它不直接面向最终用户如客服代表而是面向开发者和工程团队。Notion 用它来构建内部团队协作 agentRakuten 用它来搭建跨部门的销售/营销/财务 agent这些都不是开箱即用的成品而是嵌入到现有工作流中的定制化能力模块。它真正是什么是一个高度工程化的、托管的、安全沙箱化的 agent 执行环境hosted runtime environment。它的核心价值在于将 agent 运行时的三大关键责任从开发者肩上彻底卸下并交由一个经过大规模验证的、企业级的基础设施来承担State Management状态管理Session 数据的持久化、版本控制、查询与回溯。Execution Isolation执行隔离工具调用的安全沙箱、资源配额、凭据保密。Observability可观测性完整的、结构化的、可审计的执行轨迹记录。这三点恰恰是绝大多数自研 agent 系统在规模扩大后最先崩溃的地方。我们团队当年那个凌晨两点的 Redis 崩溃根源就在第一点——我们试图用一个为高速缓存设计的系统去承担一个为持久化日志设计的职责。这是典型的“错位使用”。2.2 “Session as Event Log”一场静默的革命Anthropic 工程博客里反复强调的 “session as durable event log living outside the model context”这句话的分量远超其字面意思。让我用一个具体场景来还原它解决的“静默崩溃”问题。假设你有一个处理保险理赔的 agent流程是用户上传事故照片和医疗报告 PDFagent 调用 OCR 工具提取文本agent 调用 NLP 工具分析伤情严重程度agent 调用规则引擎判断是否符合快速赔付条件如果符合调用支付网关发起打款如果不符合调用邮件服务发送拒赔说明。这个流程可能耗时 15-45 分钟。在传统基于 context window 的实现中每一步的输入、输出、中间思考“这张照片显示左臂有明显肿胀结合病历描述初步判断为骨折”都会被追加到一个不断增长的 message 数组里作为下一次 LLM 调用的messages参数。当这个数组长度逼近 Claude 3.5 Sonnet 的 200K token 上限时会发生什么不是优雅降级LLM 不会主动告诉你“context 即将满请清理历史”。它会默默地、毫无征兆地开始丢弃最早的消息。你可能在第 4 步还能看到清晰的 OCR 结果到了第 5 步LLM 的思考链里就只剩“用户上传了文件…需要判断赔付…”而关键的 OCR 文本和 NLP 分析结果已经从它的“记忆”里蒸发了。后果是灾难性的它可能基于一个残缺的、错误的历史做出完全错误的决策。比如因为看不到“伤情为骨折”的结论它误判为轻伤触发了快速赔付流程导致公司损失一笔不该付的钱。更可怕的是你无法复现、无法调试、无法审计。当你事后想查“为什么 agent 给了赔付”你只能看到最后几轮的对话而最关键的前几步证据已经随着 context 的滚动而永远丢失。Managed Agents 的解决方案是物理性地切断这个链条。Session 不再是 LLM 的“记忆”而是一个独立的、时间戳有序的、不可变的事件流immutable event stream。每一次 tool call 的请求、响应、元数据耗时、返回码、sandbox ID每一次 LLM 的输出包括其内部的 reasoning trace都被作为一个独立的、结构化的 event写入一个专用的、高可用的日志存储很可能是基于对象存储索引服务的组合。LLM 的 context window只负责承载当前这一轮推理所需的最小信息集例如当前任务目标、最新一条用户消息、上一轮 tool call 的简要结果摘要。状态的“真相”永远在 event log 里。提示这个设计带来的最大好处是“可确定性”determinism。你可以随时awake(sessionId)让一个挂起的 session 从任意一个已知的 event 点恢复执行而无需担心 context 的完整性。这为 long-running, human-in-the-loop 的复杂工作流提供了坚实基础。2.3 Credential Isolation生产环境的“最后一道防火墙”另一个常被低估但在生产环境中生死攸关的设计是凭据credentials的隔离。在我们早期的自研系统中为了方便我们曾把 API Key 直接作为环境变量注入到运行 agent 的 Docker 容器里。这带来了两个致命风险LLM 的“越狱”风险如果 agent 的 system prompt 或用户输入存在诱导性LLM 可能生成一段包含curl -H Authorization: Bearer your_api_key ...的代码并尝试在 sandbox 中执行。虽然 sandbox 本身是隔离的但如果凭据以明文形式存在于其环境变量中一旦 sandbox 存在未被发现的逃逸漏洞凭据就暴露了。审计与合规黑洞当安全团队要求你证明“谁在何时调用了哪个 API”你无法提供精确的、与具体 tool call 绑定的凭据使用记录。你只能证明“这个容器启动时拥有这个 Key”但无法证明 Key 是否被滥用。Managed Agents 的做法是“凭据即服务”Credentials-as-a-Service。你在 Anthropic 控制台中将各类 API Key、OAuth tokens、数据库连接串等安全地存储在他们的 Vault 中。当你在 agent 的 YAML 定义里声明一个 tool如send_slack_message你只需指定该 tool 所需的凭据类型如slack_bot_token。在 runtime当 agent 发起 tool call 时Harness执行器会向 Vault 申请一个短期、作用域受限、一次性的访问令牌short-lived, scoped, one-time-use token并将其注入到 sandbox 的执行环境中。这个令牌在本次调用结束后立即失效且其权限被严格限制在本次调用所需的最小范围内例如只能向特定 channel 发送消息不能读取历史。这不仅仅是安全加固它是一种架构上的信任委托。它意味着你不再需要信任 LLM 不会“偷看”你的环境变量你只需要信任 Anthropic 的 Vault 服务和 sandbox 的隔离机制——这两者都是经过严格审计和大规模验证的成熟组件。对于金融、医疗等强监管行业这种设计几乎是进入生产环境的强制性门槛。3. 核心细节解析与实操要点YAML 定义、Sandbox 行为与定价模型3.1 定义一个 AgentYAML 是你的“源代码”Managed Agents 的核心配置是一个 YAML 文件。这并非简单的参数列表而是一个完整的、声明式的 agent “蓝图”。让我们拆解一个生产级的、用于处理 GitHub Issue 的 agent 示例# github-issue-agent.yaml name: github-issue-resolver description: An agent that triages, investigates, and proposes fixes for GitHub issues. version: 1.2.0 # System Prompt: 这是 agent 的“人格”和“宪法” system_prompt: | You are an expert software engineer at Acme Corp, responsible for maintaining the acme-web repository. Your primary goal is to understand the users issue, reproduce it if possible, identify the root cause, and propose a concrete fix in the form of a pull request description and code diff. You MUST follow these rules: - Never assume code exists; always use the list_files and read_file tools first. - If you cannot reproduce the issue after 3 attempts, ask the user for more details or a minimal reproduction case. - Always cite the exact line numbers and file paths from your investigation. # Tools: 这是 agent 的“手脚”定义了它能做什么 tools: - name: list_files description: List all files in the specified directory of the repository. input_schema: type: object properties: path: type: string description: The directory path to list (e.g., src/components/). # 凭据绑定此 tool 使用 github_read_token credentials: github_read_token - name: read_file description: Read the contents of a specific file. input_schema: type: object properties: file_path: type: string description: The full path to the file (e.g., src/components/Button.tsx). credentials: github_read_token - name: search_code description: Search for a specific string across the entire codebase. input_schema: type: object properties: query: type: string description: The string to search for. credentials: github_read_token - name: create_pull_request description: Create a new pull request with a title, description, and proposed code changes. input_schema: type: object properties: title: type: string description: The title of the PR. description: type: string description: A detailed description of the fix and the problem it solves. base_branch: type: string default: main description: The branch to merge into. head_branch: type: string description: The new branch to create for this PR. file_changes: type: array items: type: object properties: file_path: type: string content: type: string operation: type: string enum: [create, update, delete] credentials: github_write_token # 注意此 tool 使用更高权限的 token # Guardrails: 这是 agent 的“刹车”和“护栏” guardrails: # 防止无限循环 max_tool_calls_per_session: 50 # 防止过度消耗 token max_tokens_per_call: 8192 # 防止访问敏感路径 blocked_paths: - /etc/** - /root/** - secrets/** # 强制内容安全检查 content_moderation: enabled: true policies: - hate_speech - self_harm - violence # Runtime Configuration: 这是 agent 的“硬件规格” runtime: # Sandbox 的 CPU 和内存配额 cpu: 2vCPU memory: 4GB # Session 的最大存活时间超过此时间session 自动终止 max_session_duration_hours: 8 # Sandbox 的最大执行时间单次 tool call 的超时 max_sandbox_execution_seconds: 120这个 YAML 文件就是你交付给 Anthropic 的“源代码”。它包含了 agent 的全部灵魂它知道什么system_prompt、它能做什么tools、它不能做什么guardrails、以及它有多大的力气runtime。关键在于所有这些配置都与具体的 LLM 实例解耦。你可以今天用 Claude 3.5 Sonnet明天无缝切换到 Claude 3.7 Opus只要它们的 API 接口兼容agent 的行为逻辑就不会改变。这就是“稳定抽象”的力量。3.2 SandboxCattle, Not PetsAnthropic 工程博客里那句 “Sandboxes as cattle, not pets”是理解其执行模型的关键。在传统运维中“pets” 是指那些被精心照料、有名字、有 IP、出了问题要连夜抢救的服务器而 “cattle” 是指那些编号管理、批量部署、坏了就立刻替换的虚拟机。Managed Agents 的 sandbox就是彻头彻尾的 “cattle”。按需创建用完即焚每次 agent 需要执行一个 tool call比如运行一个 Python 脚本来调用 GitHub APIHarness 就会从一个预热好的 sandbox 池中分配一个干净的、隔离的实例。这个实例在 tool call 执行完毕、返回结果后就会被立即销毁。它不会保留任何状态也不会被复用。资源硬隔离每个 sandbox 都有严格的 CPU、内存、网络带宽和磁盘 I/O 配额。一个失控的、写死循环的 Python 脚本最多只能耗尽它自己的 2vCPU 和 4GB 内存绝不会影响到同一物理主机上运行的其他 sandbox。网络策略白名单sandbox 默认是网络隔离的。它只能访问你明确允许的外部服务如api.github.com,slack.com并且只能使用你为其配置的、经过 Vault 签发的凭据。它无法访问内网数据库也无法进行 DNS 查询去探测内部网络拓扑。这种设计直接消除了“共享宿主机”模式下的所有安全隐患和性能抖动。你不需要担心一个 buggy 的 agent 会拖垮整个集群也不需要为每个 agent 单独配置复杂的防火墙规则。它就像一个一次性的、高度受控的实验室只为你当前的实验tool call服务。3.3 定价模型$0.08/session-hour 的深意Managed Agents 的定价是$0.08 per session-hour of active runtime外加标准的 Claude token 费用。这个看似简单的数字背后有深刻的工程和商业逻辑。首先明确什么是 “session-hour”它不是指 agent 被创建的总时长而是指session 处于“活跃”active状态的时间总和。一个 session 的生命周期是从第一个用户消息触发 agent 启动到 session 最终完成成功或失败并被关闭。在这期间如果 agent 因为等待用户输入、等待外部 API 响应、或执行一个长时间运行的 tool如视频转码而处于空闲idle状态这段时间不计入session-hour。只有当 Harness 正在执行 LLM 推理、或者 sandbox 正在执行 tool call 时计时器才开始走。这意味着一个处理简单问答的 session可能只消耗几秒钟的 session-hour而一个需要多次迭代、等待人工审核、再继续执行的复杂工作流其 session-hour 会累积得更多。$0.08 这个价格是经过精密计算的对标云厂商的 IaaS 成本AWS EC2 t3.medium 实例2vCPU, 4GB RAM的按需价格约为 $0.0416/hour。Anthropic 的 $0.08大致相当于在其之上叠加了 sandbox 隔离、Vault 凭据服务、event log 存储与索引、以及高级 guardrails 的成本。这是一个有利润但不过分溢价的定价旨在吸引开发者从自建方案迁移过来。小规模友好大规模有压力对于一个初创团队每月处理 1000 个平均时长 5 分钟的 sessionsession-hour 成本仅为 $0.08 * (1000 * 5 / 60) ≈ $6.67完全可以忽略。但对于一个大型企业每天处理 10 万个 session其中很多是复杂的、耗时的流程这笔费用就会迅速攀升到数万美元/月。这正是 Anthropic 的商业意图用一个合理的价格把你“锁”在 Claude 生态里让你的 token 花费成为主要成本而 runtime 成本则成为一个温和但持续的“粘性”收入。注意这个定价模型也暗示了最佳实践——尽可能优化 agent 的 workflow减少不必要的 tool calls 和 LLM 推理轮次。一个设计精良的 agent应该能在 3-5 轮内完成任务而不是陷入无休止的“思考-调用-再思考”循环。这既是成本考量也是用户体验的底线。4. 实操过程与核心环节实现从本地开发到生产部署的完整链路4.1 本地开发与测试告别“黑盒”拥抱可重现性在 Managed Agents 之前本地开发 agent 是一件痛苦的事情。你写的 YAML 或代码在本地跑得好好的一上生产环境就各种诡异问题sandbox 权限不够、凭据加载失败、网络策略拦截、甚至是因为不同版本的 Python 解释器导致的细微差异。Managed Agents 提供了一套强大的本地开发工具链其核心思想是让本地环境与生产环境尽可能一致从而消灭“在我机器上是好的”这类问题。Anthropic 提供了一个名为claude-managed-agents-cli的命令行工具。它的核心工作流如下初始化本地沙箱Local Sandbox# 创建一个与生产环境完全一致的本地 sandbox claude-managed-agents-cli sandbox init --cpu 2 --memory 4GB --network-policy ./network-policy.json这个命令会启动一个 Docker 容器模拟生产 sandbox 的所有约束CPU/Memory 配额、网络白名单network-policy.json定义了允许访问的域名和端口、以及一个模拟的 Vault 服务用于测试凭据注入。在本地沙箱中运行 Tool# 将你的 tool 代码如 github_tools.py放入 sandbox并用模拟凭据运行 claude-managed-agents-cli sandbox run --tool ./tools/github_tools.py --input {file_path: README.md} --credentials ./mock-creds/github_read_token.json这会将你的 Python 脚本在受控的 sandbox 环境中执行并返回其 stdout/stderr。你可以在这里精确地调试脚本的网络请求、文件读写、错误处理逻辑而无需担心污染本地环境。本地模拟 Session 执行# 使用你的 YAML 定义和一组测试消息模拟整个 session 流程 claude-managed-agents-cli simulate --agent ./agents/github-issue-agent.yaml --messages ./test-data/issue-123.json这个命令会启动一个本地的 Harness 模拟器。它会加载你的 YAML解析 system_prompt 和 tools。用一个轻量级的本地 LLM如 Ollama 的llama3:8b模拟 Claude 的推理过程。对于每一个 tool call它会调用你之前在 sandbox 中测试好的本地 tool。将整个执行过程包括 LLM 的输出、tool 的输入输出、耗时以结构化的 JSON 格式输出到一个trace.log文件中。这个trace.log文件就是你的本地开发“黄金标准”。它是一个完整的、可重现的、可版本控制的执行快照。你可以把它提交到 Git作为回归测试的基准。当生产环境出现异常时你只需用同样的输入消息和 YAML再次运行simulate就能 100% 复现问题而无需登录生产服务器去翻日志。4.2 生产部署与集成API 驱动的无缝嵌入Managed Agents 的生产部署完全通过 RESTful API 完成。它没有 Web 控制台的“一键部署”按钮这恰恰是其工程严谨性的体现——一切皆可编程一切皆可自动化。核心 API 流程如下注册 Agentcurl -X POST https://api.anthropic.com/v1/managed-agents \ -H x-api-key: $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d { name: github-issue-resolver, description: Triage and fix GitHub issues., config_yaml: $(cat github-issue-agent.yaml | jq -sRr uri), model: claude-3-5-sonnet-20240620 }这个 API 调用会返回一个唯一的agent_id如agnt_abc123这就是你的 agent 在 Anthropic 云上的“身份证”。启动 Sessioncurl -X POST https://api.anthropic.com/v1/managed-agents/$AGENT_ID/sessions \ -H x-api-key: $ANTHROPIC_API_KEY \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: Issue #123: Button click doesnt trigger navigation. Heres the stack trace...} ], metadata: { source: github-webhook, issue_id: 123, repo: acme-web } }这会创建一个新的 session并返回session_id和初始的response通常是 agent 的第一轮回复。metadata字段非常重要它会被自动注入到每一个 event log 中成为你后续审计和分析的关键维度。流式获取响应与处理 Tool Calls# 使用 Server-Sent Events (SSE) 流式接收响应 curl -N https://api.anthropic.com/v1/managed-agents/$AGENT_ID/sessions/$SESSION_ID/stream \ -H x-api-key: $ANTHROPIC_API_KEY这个流会推送一系列事件{type: message, content: Ill investigate this issue...}LLM 的回复{type: tool_use, name: list_files, input: {path: src/components/}}agent 决定调用 tool{type: tool_result, name: list_files, output: [Button.tsx, Header.tsx, ...]}tool 执行结果你的应用后端需要监听这个流并对tool_use事件做出响应调用你自己的内部服务如一个封装了 GitHub API 的微服务来执行真正的逻辑然后将结果通过POST /sessions/{session_id}/tool_resultsAPI 回传给 Anthropic。这个 API 驱动的模型让你可以将 Managed Agents 无缝嵌入到任何现有的技术栈中。它可以是一个 Node.js Express 应用的中间件处理来自 Slack 的事件。一个 Python FastAPI 服务作为 GitHub Webhook 的接收器。一个 Java Spring Boot 微服务集成到你的企业 Service Mesh 中。它不强迫你重构整个应用只是提供了一个强大、可靠的“智能执行单元”。4.3 监控、告警与可观测性Event Log 是你的新“仪表盘”当你的 agent 运行在 Managed Agents 上你拥有的不再是零散的日志行而是一个结构化的、富含语义的事件数据库。这才是真正的可观测性。Anthropic 提供了/v1/managed-agents/{agent_id}/sessions/{session_id}/eventsAPI你可以用它来查询任意 session 的完整事件流。但更重要的是他们提供了基于这些 event log 的高级分析能力。假设你想回答以下问题Q1过去 24 小时内哪些 tool call 的失败率最高你可以查询所有tool_result事件按name分组统计status为error的比例。你会发现search_code的失败率高达 15%而其他 tool 都低于 1%。进一步分析tool_result事件中的error_message字段发现大部分是Rate limit exceeded。这立刻指向了 GitHub API 的配额问题你需要去调整search_codetool 的凭据使用一个更高配额的 token。Q2平均来看一个 issue 从创建到 agent 提出 PR需要多少轮 LLM 推理查询所有message事件role 为assistant按session_id分组计数。你发现中位数是 4 轮但 p95 是 12 轮。这说明有少数复杂 issue 导致了长尾延迟。你可以筛选出这些长尾 session分析它们的 event log发现它们都涉及了对read_file的多次调用进而推断出 agent 的文件搜索策略效率低下需要优化list_files和search_code的协同逻辑。Q3我们的 agent 是否在无意中访问了被禁止的路径查询所有tool_use事件检查其input字段是否匹配blocked_paths规则。如果发现有匹配这不仅是安全告警更是 prompt 工程的失败信号——你的 system_prompt 没有足够清晰地约束 agent 的行为边界。实操心得我们团队在上线后的第一周就建立了一个简单的 Grafana 仪表盘将上述三个问题的指标可视化。它成为了我们每日站会的固定议程“昨天的 top 3 问题是什么我们修复了几个” 这种基于 event log 的、数据驱动的迭代比任何主观的“我觉得 agent 还行”都要可靠得多。5. 常见问题与排查技巧实录从“Why is my tool not running?” 到 “How do I debug hallucination?”5.1 常见问题速查表问题现象可能原因排查步骤解决方案Tool call 从未被触发1. LLM 的 reasoning chain 中根本没有生成tool_useblock。2. YAML 中 tool 的input_schema与 LLM 生成的inputJSON 不匹配字段名、类型错误。1. 查看message事件检查 LLM 的完整输出特别是其内部的thinking部分。2. 查看tool_use事件如果存在对比其input与 YAML 中定义的input_schema。1. 优化 system_prompt加入更明确的指令如 “When you need to read a file, ALWAYS use theread_filetool. NEVER try to guess the file contents.”2. 在 YAML 中为input_schema添加更详细的description并确保字段名与 LLM 的常用命名习惯一致如用file_path而非path_to_file。Tool call 执行失败返回Permission denied1. Sandbox 的网络策略阻止了对目标域名的访问。2. 凭据 Vault 中的 token 已过期或权限不足。1. 检查tool_use事件中的target_url确认其是否在network-policy.json的白名单中。2. 查看tool_result事件中的error_message确认是否为401 Unauthorized或403 Forbidden。1. 更新network-policy.json并重新部署 agent。2. 登录 Anthropic 控制台检查对应凭据的配置和有效期并更新。Session 在中途“消失”没有session_ended事件1. Session 超过了max_session_duration_hours。2. Harness 进程崩溃极罕见但可能。1. 检查session_started事件的时间戳计算其是否超过了配置的最大时长。2. 查看session_events的最后一条记录确认其类型。1. 在启动 session 时增加metadata字段标记其预期用途并在应用层设置一个定时器在超时前主动调用awake或end_session。2. 联系 Anthropic 支持并提供session_id这是基础设施层面的问题。LLM 的回复中出现了明显的幻觉Hallucination1. Tool call 的结果tool_result被 LLM 错误地解读或忽略了。2. System prompt 没有强制要求 LLM 必须基于 tool 结果进行推理。1. 对比tool_use事件的input和tool_result事件的output确认 tool 返回了正确信息。2. 检查message事件中 LLM 的输出看其是否提到了 tool 的结果。1. 在 system_prompt 中加入强约束“YOU MUST BASE YOUR ENTIRE REPLY ON THE OUTPUT OF THE TOOLS. IF A TOOL RETURNS DATA, YOU MUST INCORPORATE IT EXPLICITLY IN YOUR RESPONSE. DO NOT MAKE UP INFORMATION.”2. 在 YAML 的guardrails中启用content_moderation并添加factual_consistency策略如果 Anthropic 提供。5.2 独家避坑技巧从血泪教训中提炼技巧一永远为你的 Tool 编写“防御性”包装器不要让你的 Python/Node.js tool 脚本直接暴露在 sandbox 中。一定要写一个包装器wrapper它负责输入校验检查inputJSON 是否符合预期对非法输入抛出清晰的错误如{error: Invalid file_path: must be a string starting with src/}而不是让脚本崩溃。超时控制即使 sandbox 有max_sandbox_execution_seconds你的脚本内部也应设置一个更短的 timeout如 30 秒并捕获TimeoutError返回友好的错误信息。错误标准化无论底层 API 返回什么格式的错误如 GitHub 的404 Not Found或422 Unprocessable Entity你的 wrapper 都应将其统一转换为一个标准的、易于 LLM 理解的 JSON 错误结构。为什么因为 LLM 的推理能力很大程度上依赖于它接收到的tool_result的质量和一致性。一个混乱的、格式不一的错误信息会让 LLM 陷入困惑从而产生幻觉。一个清晰、结构化的错误反而能引导 LLM 做出更合理的下一步决策如“哦文件不存在那我应该先用list_files看看有哪些文件”。技巧二Session Metadata 是你的“上帝视角”metadata字段是你在 event log 中的“锚点”。不要只把它当作一个备注。你应该系统性地填充它{source: slack, channel_id: C012AB3CD, user_id: U456EF7GH}{source: web, page_url: https://acme.com/contact, utm_campaign: q2-support}这样当你在 Grafana 里看到某个 tool 的失败率
