生产级 Agent 应用架构

权限不是全开或全关的二选一——SDK 提供了一个六层洋葱模型从 Hooks 到 Deny 规则到 Permission Mode 到 Allow 规则再到 canUseTool 回调每一层都可以拦截、放行或改写工具调用。理解这个评估顺序是构建安全 Agent 的前提。前情概要前五篇我们从零构建了一个完整的 Agent 系统——Agent Loop 让它自动循环执行任务自定义工具让它调用外部能力Hooks 编排让它自我审查和多专家协作Session 管理让它拥有对话记忆和文件回滚能力流式输出让用户实时看到思考过程。至此Agent 在功能层面已经齐活了。但要上生产环境还差最关键的一环安全、权限和容错。本篇定位系列终篇解决生产级部署的四大核心问题——谁能做什么权限、多个 Agent 怎么协作架构、出错了怎么恢复容错、上线后怎么控成本保安全运维。核心看点• 权限模型的六层洋葱Hooks → Deny → Permission Mode → Allow → canUseTool → 最终裁决——每一层的职责和评估顺序• 多 Agent 协作架构三种创建方式、四个核心优势、混合模型策略用便宜模型跑子任务贵模型只做决策• 错误处理与恢复SDK 异常层级、分层 try-catch、文件检查点回滚、Session 崩溃恢复——让 Agent 从容应对网络超时和 API 错误• 生产部署四道防线部署模式选择、纵深安全策略、成本控制maxTurns / token 预算 / 实时监控、可观测性接入权限模型六层洋葱当 Claude 请求使用一个工具时SDK 按严格的六步顺序评估权限。理解这个顺序是安全设计的基础——任何一层都可以终止评估链。评估顺序第一层是 Hooks。PreToolUse钩子最先执行可以直接拒绝返回 deny或放行返回 allow。但注意Hook 返回 allow 不会跳过后续的 deny/ask 规则它只是表示我这一层没意见。第二层是 Deny 规则。来自disallowedTools配置。裸名规则如Bash直接从 Claude 的工具列表中移除——Claude 根本看不到这个工具。作用域规则如Bash(rm *)保留工具但拦截特定调用。Deny 规则在所有模式下生效包括bypassPermissions。第三层是 Ask 规则。来自settings.json。匹配时路由到canUseTool回调等待人工确认。在dontAsk模式下匹配 ask 规则的调用直接被拒绝永远不弹确认。第四层是 Permission Mode。SDK 提供六种模式typedefault// 未匹配的工具触发 canUseTooldontAsk// 未预批准的一律拒绝永不弹确认acceptEdits// 自动批准文件编辑和文件系统操作bypassPermissions// 全部放行除非有显式 ask 规则plan// 只读模式编辑类工具强制走确认auto// 模型分类器自动判断仅 TS第五层是 Allow 规则。来自allowedTools配置。匹配的工具自动批准。第六层是canUseTool回调。如果前五层都没有给出明确结论最终由这个回调决定。在dontAsk模式下这一层永远不会被触发未批准的直接拒绝。锁定模式最小权限原则生产环境最推荐的组合是allowedToolsdontAsk——白名单之外的一切都被拒绝不需要人工介入import{}anthropic-ai/claude-agent-sdk;{ prompt:分析项目代码质量 options:{ allowedTools:ReadGlobGrep// 只允许只读工具 permissionMode:dontAsk// 白名单外一律拒绝 maxTurns:15}}{// Agent 只能读取文件不能编辑、不能执行命令}动态审批canUseTool 回调对于需要人工审批的场景比如 Agent 要执行危险命令canUseTool提供了运行时拦截能力importanthropic-ai/claude-agent-sdkforofprompt修复项目中的安全漏洞optionsallowedToolsReadGlobGrepEditBashcanUseTool// 读取类工具自动放行ifReadGlobGrepincludesreturnbehaviorallow// Bash 命令需要审批ifBashconsolelog⚠️ Agent 想执行: ${input.command}ifreturnbehaviorallowreturnbehaviordenymessage用户拒绝了此命令// 文件编辑展示 diff 后审批ifEditconsolelog 修改 ${input.file_path}consolelog - ${input.old_string}consolelog ${input.new_string}returnbehaviorallow// 自动批准编辑returnbehaviorallow// 处理消息...canUseTool的返回值支持三种行为allow批准可选updatedInput改写参数、deny拒绝Claude 会看到拒绝原因并调整策略。子 Agent 权限继承一个关键的安全约束当父 Agent 使用bypassPermissions、acceptEdits或auto模式时所有子 Agent 自动继承该模式且不可覆盖。这意味着你不能在一个宽松的父 Agent 下创建一个严格的子 Agent——权限只能收紧不能放松。多 Agent 协作架构单个 Agent 处理所有任务会导致上下文膨胀、工具集过大、指令冲突。SDK 的子 Agent 机制解决这个问题——把复杂任务分解给专门的 Agent每个 Agent 有独立的上下文、工具集和系统提示。三种创建方式SDK 支持三种定义子 Agent 的方式编程式定义推荐——通过agents参数在query()调用时传入import{}anthropic-ai/claude-agent-sdk;{ prompt:审查这个 PR 的代码质量和安全性 options:{ allowedTools:ReadGrepGlobAgent// Agent 工具必须显式允许 agents:{code-reviewer{ description:代码质量审查专家。检查可维护性、设计模式、性能问题。 prompt:你是一个资深代码审查专家。关注代码质量、设计模式使用、性能瓶颈和可维护性。输出结构化的审查报告。 tools:ReadGrepGlob// 只读工具 model:sonnet}security-scanner{ description:安全漏洞扫描专家。检查注入、认证、数据泄露等安全问题。 prompt:你是一个安全审计专家。检查 SQL 注入、XSS、认证绕过、敏感数据泄露、依赖漏洞等安全问题。 tools:ReadGrepGlob model:sonnet}test-runner{ description:测试执行专家。运行测试套件并分析覆盖率。 prompt:你是一个测试工程师。运行测试、分析失败原因、报告覆盖率。 tools:BashReadGrep// 需要 Bash 来跑测试 model:haiku// 用更便宜的模型跑测试}}}}{// 父 Agent 会自动决定何时委派给哪个子 Agent// 子 Agent 的中间过程不会污染父 Agent 的上下文}文件系统定义——在.claude/agents/目录下放置 Markdown 文件适合团队共享的固定 Agent 配置。内置通用 Agent——不需要任何定义Claude 可以随时通过 Agent 工具调用一个通用子 Agent 来处理子任务。四个核心优势上下文隔离每个子 Agent 运行独立的对话。中间的工具调用和结果留在子 Agent 内部只有最终结论返回给父 Agent。这让主上下文保持精简。并行执行多个子 Agent 可以并发运行。三个独立的审查任务代码质量 安全扫描 测试覆盖的总耗时等于最慢的那个而不是三者之和。专业化指令每个子 Agent 有独立的系统提示可以针对特定任务深度优化不会和其他任务的指令冲突。工具限制子 Agent 只能使用你显式授予的工具。一个只做代码审查的 Agent 不需要也不应该有文件编辑权限。AgentDefinition 完整配置interfaceAgentDefinitiondescriptionstring// 必填何时使用这个 Agent驱动自动委派promptstring// 必填Agent 的系统提示toolsstring// 允许的工具列表省略则继承全部disallowedToolsstring// 禁止的工具modelstring// haiku | sonnet | opus | inherit | 完整模型 IDmaxTurnsnumber// 最大轮次mcpServersstringobject// MCP 服务器成本优化混合模型策略多 Agent 架构的一个隐藏优势是可以按任务复杂度分配模型。主 Agent 用 Opus 做决策和协调子 Agent 用 Sonnet 或 Haiku 做执行// 主 Agent: Opus默认负责理解需求、拆分任务、综合结论// code-reviewer: Sonnet 做深度代码分析// test-runner: Haiku 跑测试不需要深度推理// doc-generator: Haiku 生成文档模板化工作ResultMessage的modelUsage字段会按模型分别统计 token 用量和成本方便你追踪混合模型策略的实际效果。错误处理与恢复策略生产环境的 Agent 必须优雅地处理各种失败场景。SDK 的错误体系分为两个层面进程级错误SDK 本身的异常和任务级错误Agent 执行过程中的问题。SDK 异常层级# 所有 SDK 错误的基类# Claude Code 二进制文件未找到# 无法连接到 CLI 进程# CLI 进程异常退出stderr# 退出码和错误输出# 无法解析 CLI 输出的 JSONline# 原始行和解析错误# JSON 有效但不符合消息 schema# 原始数据分层错误处理importfromanthropic-ai/claude-agent-sdkasyncfunctionrunAgentWithRecoveryprompt: string, maxRetries 3forlet1tryconstforawaitconstofqueryoptionsallowedToolsReadEditBashmaxTurns20abortControllercreateTimeoutController60_000// 60 秒超时iftyperesultswitchsubtypecasesuccessreturnsuccesstruecosttotal_cost_usdturnsnum_turnscaseerror_max_turns// Agent 陷入循环缩小任务范围重试consolewarn⚠️ 达到最大轮次 (${message.num_turns})尝试缩小范围${prompt}\n\n注意上次尝试超时了。请只处理最关键的部分不要试图一次解决所有问题。breakcaseerror_during_execution// 执行错误记录后重试consoleerror❌ 执行错误 (尝试 ${attempt}/${maxRetries})breakcatchifnameAbortErrorconsoleerror⏱️ 超时 (尝试 ${attempt}/${maxRetries})continue// SDK 级别错误ifconstructornameCLINotFoundErrorthrownewErrorClaude Code 未安装无法恢复ifconstructornameProcessErrorconsoleerror进程错误: exit${err.exit_code}, stderr${err.stderr}ifawaitsleep1000// 指数退避continuethrow// 未知错误向上抛出returnsuccessfalseerror达到最大重试次数functioncreateTimeoutControllerms: numberAbortControllerconstnewAbortControllersetTimeout() abortreturn文件检查点可回滚的修改当 Agent 修改文件出错时File Checkpointing 提供了后悔药。结合错误检测可以实现自动回滚fromanthropic-ai/claude-agent-sdkforawaitconstqueryprompt重构认证模块optionsallowedToolsReadEditWriteBashrewindFilestrueifresultifsuccess// 任务失败回滚所有文件修改log任务失败正在回滚文件修改...// rewindFiles 会自动恢复到任务开始前的状态Session 恢复崩溃后继续结合第四篇的 Session 机制可以实现崩溃恢复importfromanthropic-ai/claude-agent-sdkconstSESSION_IDmigration-task-001constnewRedisSessionStore// 尝试恢复之前的会话asyncfunctionrunOrResumeprompt: stringconstawaitloadSESSION_IDforawaitconstofquerypromptundefined// 恢复时不需要新 promptoptionsresumeSESSION_IDundefinedallowedToolsReadEditWriteBashiftyperesultifsubtypesuccessconsolelog✅ 任务完成awaitdeleteSESSION_ID// 失败时 session 自动保存下次启动可恢复生产部署安全与成本部署模式选择SDK 的子进程模型决定了部署架构。query()每次调用都会启动一个claudeCLI 子进程通过 stdio 通信。选择部署模式时需要考虑会话生命周期短任务Ephemeral模式一个容器处理一个任务完成后销毁。适合一次性任务bug 修复、文档翻译、数据提取。冷启动要快。长驻Long-running模式持久容器内部运行多个 SDK 进程。适合持续服务邮件分类、Slack 机器人、实时监控。用startup()预热按最大并发会话数规划内存。混合Hybrid模式容器按需启动通过 SessionStore 恢复状态。适合交互间隔长的场景跨天的代码审查、多轮文档协作。SessionStore 是必需的——没有它容器销毁时会话就丢了。安全纵深防御Agent 的核心安全风险是提示注入——恶意指令可能嵌入在 README、网页、用户输入中。SDK 内置了多层防护但生产环境需要额外加固容器隔离\\# 移除所有 Linux capabilitiesnonew\# 禁止提权to\# seccomp 限制系统调用\# 只读文件系统\# 临时目录禁止执行\# 无网络或用代理限制代理模式Proxy Pattern敏感凭证不进入 Agent 的边界。在 Agent 外部放一个代理Agent 发出的 API 请求经过代理时自动注入认证信息Agent → HTTP Request (无凭证) → Proxy (注入 API Key) → 外部服务这样即使 Agent 被提示注入攻击攻击者也拿不到凭证。最小权限清单资源限制方式文件系统只挂载必要目录优先只读网络通过代理限制可访问的域名凭证代理注入Agent 永远看不到系统能力容器内 drop 所有 capabilities工具allowedToolsdontAsk白名单成本控制四道防线第一道maxTurns限制。防止 Agent 陷入无限循环。根据任务复杂度设置合理上限。第二道AbortController超时。防止单次任务耗时过长。第三道实时成本监控。通过ResultMessage.total_cost_usd追踪每次调用的成本importfromanthropic-ai/claude-agent-sdkconstCOST_LIMIT_PER_TASK1.00// 单任务上限 $1constCOST_LIMIT_DAILY50.00// 日上限 $50let0asyncfunctionrunWithCostGuardprompt: stringconstnewAbortControllerforawaitconstofqueryoptionsabortControllermaxTurns30allowedToolsReadEditWriteBashiftyperesultconsttotal_cost_usdifCOST_LIMIT_PER_TASKconsolewarn⚠️ 单任务成本超限: $${cost.toFixed(4)}ifCOST_LIMIT_DAILYconsoleerror 日成本超限: $${dailyCost.toFixed(2)}暂停所有任务abort// 按模型分别统计ifmodelUsageforconstofObjectentriesmodelUsageconsolelog ${model}: $${usage.costUSD.toFixed(4)} (${usage.inputTokens}${usage.outputTokens} tokens)第四道混合模型策略。主 Agent 用高能力模型子 Agent 按需降级complex-analysismodelopus// 复杂推理用 Opuscode-generationmodelsonnet// 代码生成用 Sonnetsimple-tasksmodelhaiku// 简单任务用 Haiku可观测性生产环境需要追踪 Agent 的行为。关键指标metrics.record({ task_id.subtype.duration_ms.duration_api_ms.num_turns.total_cost_usd.usage.input_tokens.usage.output_tokens.usage.cache_read_input_tokens.modelUsage建议接入 OpenTelemetry 分布式追踪每个query()调用作为一个 span子 Agent 调用作为子 span。完整示例生产级代码审查 Agent把前面所有知识组合起来这是一个可以部署到生产环境的代码审查 Agentimportanthropic-ai/claude-agent-sdksuccess:findings:cost:duration:diff:sessionStore:ReviewResultabort120//2letletresult:success:falsefindings:cost:0duration:0prompt:options://allowedTools:ReadGrepGlobAgentpermissionMode:dontAskmaxTurns:15abortController://agents:quality-checkerdescription:代码质量审查命名、结构、复杂度、重复代码prompt:你是代码质量专家。检查命名规范、函数复杂度、代码重复、设计模式使用。输出 JSON 格式的发现列表。tools:ReadGrepGlobmodel:sonnetsecurity-auditordescription:安全审计注入、认证、数据泄露、依赖漏洞prompt:你是安全审计专家。检查 SQL 注入、XSS、CSRF、认证绕过、敏感数据暴露。按严重程度排序输出。tools:ReadGrepGlobmodel:sonnet//includePartialMessages:trueifstream_eventifcontent_block_starttool_useifassistantiftextifresultresultsuccess:successcost:duration:ifAbortErrorsuccess:falsefindings:审查超时cost:0duration:120throw这个示例综合运用了权限锁定dontAsk 只读工具、多 Agent 并行质量 安全两个子 Agent、超时控制AbortController、流式输出实时展示进度、Session 持久化崩溃可恢复、成本追踪ResultMessage。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】