跳转到内容
AI Agent 教程 AI Agent 教程

03 LLM 应用三层架构与决策树

03 LLM 应用三层架构与决策树

学习目标

  • 理解 claude-api 技能中的三层架构决策树
  • 掌握 Anthropic 对 Agent 四准则检查的定义
  • 分析 Managed Agents 在技能中的具体组织方式
  • 学习模型选择与 effort 参数的调优策略

前置知识

本章涉及 LLM 应用三层架构的通用原理，建议先阅读：

下文假设你已理解上述概念，直接聚焦 claude-api 技能的具体实现。

项目实践

claude-api 技能的决策树实现

claude-api 是 Anthropic Skills 仓库中最大的技能（18 个子目录，8 种语言支持），其 SKILL.md 的核心是一个五步决策树：

这个决策树的独特之处在于第 0 步：先检查部署环境。Anthropic 明确指出 Managed Agents 仅限第一方（Anthropic 直接 API），不在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上可用。

Agent 四准则检查的明确定义

在 skills/claude-api/SKILL.md 的 “Should I Build an Agent?” 部分：

准则具体问题负面示例正面示例
Complexity任务是否多步且难以完全指定？“从 PDF 提取标题""把设计文档变成 PR”
Value结果价值是否值得更高成本和延迟？简单格式化高价值研究分析
ViabilityClaude 在此类任务上是否有能力？精确数学计算代码生成、研究分析
Cost of error错误能否被发现和恢复？无测试、无审查有测试覆盖、代码审查

任何一项为 No → 不使用 Agent。这是 Anthropic 对开发者的明确建议，而非模糊指导。

Managed Agents 的技能组织方式

claude-api 技能中，Managed Agents 相关的概念文件完全放在 shared/ 目录下，与语言无关：

文件内容
shared/managed-agents-overview.md完整阅读指南 + Beta 头 + 常见陷阱
shared/managed-agents-core.md核心 API：Agents、Sessions、Messages
shared/managed-agents-tools.md工具定义与执行
shared/managed-agents-events.mdSSE 事件流解析
shared/managed-agents-environments.md环境配置与隔离
shared/managed-agents-memory.md持久化记忆
shared/managed-agents-multiagent.md多 Agent 协作
shared/managed-agents-webhooks.mdWebhook 通知
shared/managed-agents-onboarding.md新用户引导访谈脚本
shared/managed-agents-client-patterns.md客户端代码模式与常见陷阱
shared/managed-agents-outcomes.mdAgent 结果处理
shared/managed-agents-api-reference.mdAPI 端点完整参考
shared/managed-agents-self-hosted-sandboxes.md自托管沙箱配置

每个语言（Python、TypeScript、Go、Ruby、Java、PHP、cURL）在自己的目录下只有一个 managed-agents/README.md，提供代码示例并指向 shared/ 的概念文件。

模型选择与 effort 参数的精细化

claude-api 技能中对模型选择的规则非常严格：

ALWAYS use claude-opus-4-7 unless the user explicitly names a different model. This is non-negotiable.

关于 effort 参数（GA，无需 Beta 头）：

effort 值适用模型适用场景
lowOpus 4.5+, Sonnet 4.6子代理、简单任务
high（默认）Opus 4.5+, Sonnet 4.6大多数智能敏感任务
xhigh仅 Opus 4.7编码和 Agent 用例（Claude Code 默认）
maxOpus 4.6+（非 Sonnet/Haiku）正确性比成本更重要的场景

关键洞察：Opus 4.7 上 effort 的影响比任何之前的 Opus 都大——迁移到 4.7 时需要重新调优 effort 值。

问题与规避

在非 Anthropic 项目中使用 claude-api 技能

问题：技能会检查项目中是否有 import openai、from openai、OpenAI( 等非 Anthropic 标记。如果检测到，会停止并告知用户此技能仅产出 Claude/Anthropic SDK 代码。

规避策略：这是有意设计的保护机制，防止错误地将 Anthropic SDK 调用混入其他提供者的项目。

模型迁移范围不明确

问题：用户说”迁移到 Sonnet 4.6”但不指定具体文件。

规避策略：技能明确要求先询问作用域——整个工作目录、特定子目录还是特定文件列表。只有当提示中明确指出了确切文件、目录或文件列表时，才无需询问。

设计取舍

为什么用单一大型技能而非多个小技能？

claude-api 技能包含了 8 种语言的全部教程、Managed Agents 的 13 个概念文件、以及多个共享概念文档。

优势：所有相关知识在一个技能中，减少技能间的切换和上下文丢失。 代价：SKILL.md 本身超过 300 行（加上引用的文件远超 500 行）。 Anthropic 的权衡：用 SKILL.md 作为路由器，具体细节在 shared/ 和语言子目录中按需加载。

为什么对模型选择如此严格？

优势：避免开发者因不了解最新模型而使用过时的模型 ID 或追加日期后缀。 代价：可能限制了有特定成本考量的开发者的灵活性。 Anthropic 的立场：默认 Opus 4.7 是”不可协商的”——降级模型应该是用户主动决定，而非技能自动选择。

参考来源

版本信息

📅 2026-05-28 🏷️ 690f15c 🔀 690f15c

标签

llm-apparchitectureagent-designmanaged-agents

相关通用知识