为何链式智能体技能会失效,以及可行的三层修复方案
复杂的技能链会超出智能体的处理能力上限。应采用原子、分子和化合物的方式来构建,同时提供Claude Code、LangGraph、CrewAI和Agno的示例。
来源: Why AI Agent Skills Break When We Chain Them and the Three-Layer Fix
智能体技能链的层级越多,智能体遗忘的内容就越多。三层结构模式能够确保无论处于何种深度,技能都能保持稳定性,这一模式在 Claude Code、LangGraph、CrewAI 和 Agno 中均适用。
为何扁平化的技能图会失效
从理论上讲,技能图颇具吸引力:将各种技能相互关联,让智能体沿着图结构移动,并根据需求组合出所需能力。例如,一个营销技能可以调用研究技能,而研究技能再调用抓取技能,这样就形成了自动化的处理流程。
但在实际应用中,这种模式会在 Claude Code、Codex、Cursor 以及所有上下文窗口大小有限的智能体中失效。
其工作机制如下:该智能体最初仅加载技能描述,这已足以让其了解存在的技能种类。当实际使用某项技能时,其完整内容才会被加载,并保留在会话中,从而占用上下文空间。Claude Code公开说明了自身的限制:一旦会话被压缩,单个技能最多可保留5,000个标记,所有技能合计最多为25,000个标记。仅五个完整技能就已接近这一上限,若加载十个,则会有内容在无预警情况下被丢弃。其他智能体也会遇到类似限制,只是具体数值有所不同。
不同框架的开发者都描述了相同的状况:直接调用B能稳定运行,而通过A再调用B再调用C则效果参差不齐,至于通过A再调用B再调用C再调用D,更多只能寄希望于运气而非可靠的实现方式。最终,智能体会面临太多指令争抢注意力,而可用于存储这些指令的空间又过于有限的问题。
技能组合本身并非糟糕的想法,问题在于将其以平面图的形式呈现。此处示例采用 Claude Code 的 SKILL.md 格式,因其文档最为清晰,但“原子、分子与化合物”这一模型同样适用于任何拥有技能、工具或插件的智能体。
与实际技能组合相匹配的三个层级
大多数智能体框架早已实现了分层结构:直接使用的工具、串联的工作流以及对子智能体的委托。Claude Code 通过命令、技能和任务的三级层级结构将其明确体现出来。以下三个层级分别对应 Codex(技能与命令)、Cursor(规则与工具),以及任何支持工具调用和子进程的系统。
原子:一个技能,一项任务
原子指的是用于执行单一特定任务的 SKILL.md 文件,其行为几乎具有确定性。它不会调用其他技能,也不会做出任何判断,拥有明确的输入和输出。
---
name: verify-email
description: Verify an email address using Hunter.io API.
Use when validating email deliverability before outreach.
allowed-tools: Bash
---
## Verify Email
1. Read the Hunter API key from $HUNTER_API_KEY
2. Call the Hunter email-verifier endpoint
3. Return: status (deliverable/risky/undeliverable), score, smtp_check
4. If the API errors, report the error. Do not guess.
一个简单的测试:如果你能用一句话描述某项技能而不使用“和”字,那它就是一个原子。其他例子包括将URL转换为Markdown格式、运行测试套件、检查文件格式、获取拉取请求的差异内容或查询DNS记录。
分子:由原子按顺序连接而成的结构
分子通过按固定顺序执行两个到十个原子来解决更复杂的问题。它与技能图的区别在于其执行流程是明确写下来的。分子不需要模型在运行时去发现存在哪些原子并猜测执行顺序。
---
name: qualify-lead
description: Research a company, find the right contact, verify
their email, output a qualified lead card.
allowed-tools: Bash Read Write
---
## Qualify Lead
Execute these steps IN ORDER.
### Step 1: Company Research
Use /research-company. Capture: size, industry, funding, tech stack.
### Step 2: Find Contact
Use /find-contact. Target: VP Eng, CTO, Head of Platform.
### Step 3: Find & Verify Email
Use /find-email, then /verify-email.
If undeliverable, return to Step 2 (max 3 attempts).
### Step 4: Output Lead Card
Write structured markdown to leads/{company-slug}.md
注意该文件刻意回避了什么内容。它从未要求智能体自行判断需要哪些技能,而是明确列出了操作顺序:先研究公司,再寻找联系人,接着找到邮箱地址,最后进行验证,必须按此顺序进行。
正是这种明确的指令才保证了可靠性。像“研究公司并找到联系他们的最佳方式”这类模糊的指示会让模型在运行时自行选择操作步骤,有时甚至会跳过某些环节或临时拼凑出完全忽略既定步骤的工作流程。
复合体:协调子智能体
当单个上下文窗口无法容纳所有信息时,就需要使用复合体。它们会借助 Claude Code 的任务工具来启动多个子智能体,每个子智能体都有独立的上下文窗口和预加载的技能。
---
name: outbound-playbook
description: Run the full outbound playbook for a target segment.
Spawns parallel agents to qualify leads and draft emails.
disable-model-invocation: true
allowed-tools: Bash Read Write Task Teammate
---
## Outbound Playbook
### Phase 1: Build Lead List
Ask the user for: target segment, company size range, geography.
Use /scrape-directory to pull matching companies.
### Phase 2: Parallel Lead Qualification (Task tool)
For each company (batch of 5):
- Spawn a subagent with qualify-lead preloaded
- Each subagent qualifies one company independently
### Phase 3: Draft Emails (Task tool)
For each qualified lead:
- Spawn a subagent with draft-email preloaded
### Phase 4: Human Review Checkpoint
STOP. Present sample drafts. Ask: "Review these. Adjust or proceed?"
Do NOT proceed without explicit user approval.
### Phase 5: Campaign Summary
Compile results to outbound/{segment}/campaign-summary.md
有两项特性让复合系统与众不同。首先,子代理拥有独立的上下文窗口,因此客户筛选工作不会与邮件起草在资源占用上产生冲突。正因如此,复合系统的处理能力能够突破限制深层链路的瓶颈。
其次,disable-model-invocation: true意味着只有人类才能启动该流程。模型无法自行决定发起外联营销活动。由于复合系统会触发实际操作,因此必须由人类来掌控最终决策权。
文件夹结构
.claude/skills/
# ATOMS — single purpose, near-deterministic
verify-email/SKILL.md
find-email/SKILL.md
find-contact/SKILL.md
research-company/SKILL.md
scrape-url/SKILL.md
# MOLECULES - explicit chains of atoms
qualify-lead/SKILL.md
review-and-test/SKILL.md
draft-blog-post/SKILL.md
# COMPOUNDS - subagent orchestration, human-driven
outbound-playbook/SKILL.md
feature-build-ship/SKILL.md
名称具有灵活性,关键在于分隔方式。
其他地方的类似理念
这里的内容并非SKILL.md所独有。所有主流智能体框架都有类似功能,虽然语法会有所不同,但组合逻辑保持一致。
LangGraph:工具、链与子图
在LangGraph中,原子是由@tool装饰的函数;分子是具有明确节点顺序的顺序图;而化合物则是具有独立状态的子图。
from langgraph.graph import StateGraph
from langchain_core.tools import tool
# ATOM: a single tool
@tool
def verify_email(email: str) -> dict:
"""Verify email deliverability via Hunter.io."""
response = requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}")
return response.json()
# MOLECULE: explicit sequential graph
workflow = StateGraph(LeadState)
workflow.add_node("research", research_company)
workflow.add_node("find_contact", find_contact)
workflow.add_node("verify", verify_email)
workflow.add_edge("research", "find_contact")
workflow.add_edge("find_contact", "verify")
graph = workflow.compile()
# COMPOUND: subgraph composition
parent = StateGraph(CampaignState)
parent.add_node("qualify", qualify_subgraph) # each is a compiled graph
parent.add_node("draft", email_subgraph) # with its own state
parent.add_node("review", human_review_node)
它与 Claude Code 的不同之处在于,LangGraph 的“分子”是一种具有明确边关系的图结构,而非指令列表,因此调度是基于结构而非文本的。这样一来,条件判断、循环和并行分支能够更自然地实现,不过初始化需要更多的代码。
CrewAI:流程中的工具、任务与团队
CrewAI 的结构非常清晰。原子代表工具,分子是由带有 context 依赖关系的任务链构成的,而化合物则是由流程驱动的团队。
from crewai import Agent, Task, Crew, Flow
from crewai.tools import tool
# ATOM: a tool
@tool
def verify_email(email: str) -> str:
"""Verify email deliverability."""
return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text
# MOLECULE: tasks chained via context
researcher = Agent(role="Researcher", goal="Find company info", tools=[search_tool])
verifier = Agent(role="Verifier", goal="Verify contacts", tools=[verify_email])
research_task = Task(description="Research {company}", agent=researcher)
verify_task = Task(description="Verify the contact", agent=verifier, context=[research_task])
crew = Crew(agents=[researcher, verifier], tasks=[research_task, verify_task])
# COMPOUND: Crews inside a Flow
class OutboundFlow(Flow):
@start()
def qualify_leads(self):
return qualify_crew.kickoff(inputs={"segment": self.state.segment})
@listen(qualify_leads)
def draft_emails(self, qualified):
return email_crew.kickoff(inputs={"leads": qualified})
@listen(draft_emails)
def human_review(self, drafts):
return drafts # pause for human approval
context=[research_task] 参数是明确的关联机制。该参数指示验证任务需等待研究任务完成后再执行,并读取研究任务产生的结果。若不设置该参数,每个任务将独立运行,从而失去这种关联关系。
Agno:工具、智能体与团队
Agno 的映射结构最为简单。原子对应 @tool 函数,分子则是包含多个工具及用于确定执行顺序的描述信息的智能体,而化合物则采用团队结构来表示。
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools import tool
# ATOM
@tool
def verify_email(email: str) -> str:
"""Verify email deliverability via Hunter.io."""
return requests.get(f"https://api.hunter.io/v2/email-verifier?email={email}").text
# MOLECULE: agent with ordered tools
qualify_agent = Agent(
model=Claude(id="claude-sonnet-4-6"),
description="Qualify a lead: research company, find contact, verify email. Execute in that order.",
tools=[research_company, find_contact, find_email, verify_email],
)
# COMPOUND: team of agents
from agno.team import Team
outbound_team = Team(
agents=[qualify_agent, email_drafter, campaign_reporter],
description="Run the full outbound playbook for a target segment.",
)
由于排序信息存在于描述中,Agno的分子结构更类似于SKILL.md的实现方式,而非LangGraph的结构化边。这种方式更易于编写,且在排序方面略少确定性。
一种架构,多种语法
实现细节可能有所不同,但整体结构不变。任何超越简单演示阶段的框架最终都会采用相同的三层结构,因为各处的约束条件都是一样的:有限的上下文、不可靠的自动关联机制,以及在高风险任务中需要人工监督。
仍然存在的缺陷
- 弱原子会破坏其上方的所有结构。如果某个验证邮箱的原子在API实际失败时仍报告成功,那么所有依赖它的分子和复合体都会产生错误结果。在组合使用之前应逐一测试这些原子。
- 原子数超过10的分子可靠性会下降。在Claude Code中,压缩后的总资源预算存在固定上限,其他智能体也有各自的限制。建议将分子原子数控制在2到10之间,并将关键步骤放在早期阶段。
- 由8到10个分子构成的化合物也会遇到性能瓶颈。协调器需要跟踪各个子智能体的完成情况、产出结果以及后续步骤,但当规模超过一定限度时,它就无法有效管理流程。此时应将较大的化合物拆分为两个部分,并在两半之间设置人工检查点。
- 自动调用方式不如手动调用可靠。Vercel公布的智能体评估结果显示,在大量测试用例中某些功能并未被自动调用,这一现象在Claude Code之外很可能同样存在。对于原子而言这种情况尚可接受,但对于分子和化合物,则应关闭自动调用功能,由人工手动触发。
你是驾驶员,而智能体则是引擎。
为何这很重要
稀缺的资源并非计算能力或令牌,而是你的注意力。输入“验证此邮件”与输入“为金融科技领域执行外发操作”在启动和监控时所需的心力大致相同,但产生的结果却有天壤之别。
简而言之,原子为智能体提供可预测的工作单元,分子将这些单元串联成能够完成特定任务的序列,而化合物则能在不同的上下文窗口中并行运行多个序列。每一层都会增加输出,而你的注意力却基本保持不变。
这种架构已得到支持,Claude Code中就有明确实现,其他地方也有类似的构造。大多数开发者尚未构建的,正是这种组合模式。
Claude Code的技能文档位于code.claude.com/docs/en/skills,其SKILL.md格式遵循可在多种AI工具中使用的开放型Agent Skills标准。原子、分子和化合物是一种拟定的结构模式,所示代码为伪代码,用于解释相关概念。
相关阅读
- Agent在生产环境中的工具使用:来源追溯、重试机制与可观测性 —— 某银行开发的Agent错误调用了付费API并编造了电话号码。本文介绍了最低限度的工具组合、参数来源追溯、三级重试机制以及针对不同工具的指标设置。