Strona główna / Artykuły

Dlaczego łańcuchy umiejętności agenta zawodzą oraz trójwarstwowe rozwiązanie, które to naprawia

Złożone łańcuchy umiejętności przeciążają kontekst agenta. Zamiast tego buduj z atomów, cząsteczek i związków, podając przykłady dla Claude Code, LangGraph, CrewAI i Agno.

Wydawca: REACTAPP.TOP9 min czytania1996 słów

Źródła: Why AI Agent Skills Break When We Chain Them and the Three-Layer Fix

Im więcej warstw ma łańcuch umiejętności agenta, tym bardziej ten agent zapomina. Wzorzec składu trzech warstw zapewnia niezawodność umiejętności na każdej głębokości i jest stosowany w Claude Code, LangGraph, CrewAI oraz Agno.

Dlaczego proste grafy umiejętności zawodzą

Na papierze graf umiejętności wydaje się atrakcyjny: łączy się umiejętności ze sobą, agent może przemieszczać się po tym grafie i budować potrzebne funkcje. Umiejętność marketingowa wywołuje umiejętność badawczą, która z kolei wywołuje umiejętność pobierania danych, co tworzy zautomatyzowany proces.

W praktyce taki model zawodzi w Claude Code, Codex, Cursor oraz we wszystkich innych agentach, których okno kontekstowe jest skończone.

Oto ten mechanizm. Agent najpierw ładuje jedynie opisy umiejętności, co wystarcza, by wiedzieć, co istnieje. Pełna treść umiejętności jest ładowana w momencie jej wywołania i pozostaje w sesji, zużywając przy tym kontekst. Claude Code otwarcie dokumentuje swoje ograniczenia: po skompresowaniu sesji pojedyncza umiejętność może zawierać maksymalnie 5 000 tokenów, a wszystkie umiejętności razem – 25 000. Już pięć pełnych umiejętności zbliża się do tego limitu. Gdy dodamy dziesięć, część informacji zostanie usunięta bez uprzedzenia. Inne agenty napotykają podobne bariery, choć z różnymi liczbami.

Rozwijający oprogramowanie w różnych frameworkach opisują tę samą sytuację. Wywołanie B działa niezawodnie. Sekwencja A do B do C daje różne wyniki. Sekwencja A do B do C do D to bardziej kwestia nadziei niż rzetelnej inżynierii. Agent kończy z zbyt wieloma instrukcjami walczącymi o uwagę i zbyt małą ilością miejsca na ich przechowywanie.

Umiejętności kompozycji same w sobie nie są złą koncepcją. Problemem jest ich przedstawianie w postaci prostego wykresu. Przykłady tutaj wykorzystują format SKILL.md z Claude Code, ponieważ jego dokumentacja jest najjasniejsza, ale ten model atomów, cząsteczek i związków odnosi się do każdego agenta posiadającego umiejętności, narzędzia lub wtyczki.

Trzy poziomy odpowiadające rzeczywistej kompozycji

Większość frameworki dla agentów już dzieli funkcjonalności na warstwy: bezpośrednie narzędzia, łańcuchowe procesy pracy oraz delegowanie zadań podagentom. Claude Code czyni to jawne dzięki hierarchii poleceń, umiejętności i zadań. Poniższe trzy poziomy odpowiadają Codexowi (umiejętności i polecenia), Cursorowi (reguły i narzędzia) oraz wszystkiemu, co umożliwia wywoływanie narzędzi i obsługę podprocesów.

Atomy: jedna umiejętność, jedno zadanie

Atom to plik SKILL.md przeznaczony do wykonywania jednego, konkretnego zadania o niemal deterministycznym zachowaniu. Nie wywołuje żadnych innych umiejętności ani nie podejmuje decyzji. Ma wyraźny wejście i wyjście.

---
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.

Prosty test: jeśli potrafisz opisać całą umiejętność w jednym zdaniu bez użycia słowa „i”, to jest to atom. Inne przykłady to konwertowanie URL na format markdown, uruchamianie zestawu testów, sprawdzanie poprawności pliku, pobieranie różnic w pull-requestach lub wyszukiwanie rekordów DNS.

Molekuły: spisane łańcuchy atomów

Molekuła rozwiązuje większy problem poprzez uruchamianie od dwóch do dziesięciu atomów w określonej kolejności. To, co odróżnia ją od grafu umiejętności, to to, że ta organizacja jest spisana. Molekuła nie polega na tym, by model odkrywał, które atomy istnieją, i zgadywał kolejność w czasie wykonywania.

---
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

Zwróć uwagę na to, czego plik unika mówienia. Nigdy nie poleca agentowi, aby samodzielnie określił, jakie umiejętności są mu potrzebne. Określa jedynie sekwencję działań: zbadanie firmy, znalezienie kontaktu, znalezienie adresu e-mail, a następnie jego weryfikacja, w tym właśnie porządku.

Właśnie ta precyzja zapewnia niezawodność. Niejasne polecenie typu „zbadaj firmę i znajdź najlepszy sposób na nawiązanie z nimi kontaktu” sprawia, że model musi na bieżąco wybierać odpowiednie kroki, a czasami pomija jakiś etap lub improwizuje proces, ignorując Twoje wytyczne.

Składniki: koordynacja podagentów

Składniki pojawiają się wtedy, gdy jedno okno kontekstowe nie jest w stanie pomieścić wszystkiego. Wykorzystują narzędzie Task w Claude Code do uruchamiania podagentów, z których każdy ma własne okno kontekstowe oraz własne, wcześniej załadowane umiejętności.

---
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

Dwie cechy wyróżniają rozwiązania typu compounds. Po pierwsze, podagenty mają oddzielne okna kontekstowe, dzięki czemu praca nad weryfikacją leadów nie konkuruje z tworzeniem e-maili o ograniczonej przestrzeni. Dlatego rozwiązania typu compounds mogą rosnąć poza te ograniczenia, które utrudniają pracę z złożonymi łańcuchami operacji.

Po drugie, disable-model-invocation: true oznacza, że tylko człowiek może uruchomić plan działania. Model nie może samodzielnie zdecydować o rozpoczęciu kampanii. Rozwiązania typu compounds wyzwalają działania w rzeczywistym świecie, więc osoba ludzka powinna mieć kontrolę nad nimi.

Struktura folderów

.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

Nazwy są elastyczne. Liczy się rozdzielenie.

Ta sama koncepcja gdzie indziej

Nic tutaj nie jest specyficzne dla SKILL.md. Każda główna ramka agentów ma swoje odpowiedniki, a składnia się zmienia, choć logika kompozycji pozostaje niezmienna.

LangGraph: narzędzia, łańcuchy, podgrafy

W LangGraph atomy to funkcje ozdobione tagiem @tool, cząsteczki to sekwencyjne grafy z wyraźnym porządkiem węzłów, a związki to podgrafy z odrębnym stanem.

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)

Różnica w porównaniu z Claude Code polega na tym, że cząsteczka LangGraph to graf z wyraźnie zdefiniowanymi krawędziami, a nie lista instrukcji, więc orkiestracja ma charakter strukturalny, a nie tekstualny. Warunki, pętle i równoległe gałęzie występują w ten sposób naturalniej, chociaż konfiguracja wymaga więcej kodu.

CrewAI: narzędzia, zadania, zespoły w ramach przepływów

CrewAI umożliwia przejrzyste mapowanie. Atomy to narzędzia, cząsteczki to zadania połączone łańcuchem z zależnościami context, a związki to zespoły uruchamiane przez przepływy.

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

Parametr context=[research_task] stanowi wyraźne powiązanie. Ten parametr poleca zadaniu weryfikacji, aby czekało aż zadanie badawcze zostanie zakończone, a następnie przeczytało to, co zostało wytworzone. Jeśli go pominąć, każde zadanie będzie działać samodzielnie, w związku z czym łańcuch zaniknie.

Agno: narzędzia, agenci, zespoły

Agno posiada najprostsze mapowanie. Atomy to funkcje @tool, cząsteczka to agent zawierający kilka narzędzi oraz opis określający kolejność wykonywania, natomiast związki chemiczne wykorzystują konstrukcję zespołu.

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.",
)

Ponieważ kolejność znajduje się w opisie, cząsteczka Agno bardziej przypomina podejście SKILL.md niż strukturalne krawędzie LangGraph. Jest prostsza w napisaniu i nieco mniej deterministyczna jeśli chodzi o kolejność.

Jedna architektura, wiele składni

Detale implementacji się różnią, ale struktura pozostaje taka sama. Każda platforma, która wyrośnie poza proste demonstracje, ostatecznie składa się z tych samych trzech warstw, ponieważ ograniczenia są wszędzie identyczne: skończony kontekst, niewiarygodne automatyczne łączenie elementów oraz konieczność nadzoru człowieka przy pracach o wysokim stopniu ryzyka.

Gdzie nadal zawodzi

  • Słabe elementy psują wszystko, co znajduje się nad nimi. Jeśli element verify-email zgłasza sukces, podczas gdy API faktycznie zawiodło, każda cząsteczka i związek, który na nim polega, generuje błędne wyniki. Testuj elementy pojedynczo przed ich łączeniem.
  • Molekuły składające się z ponad dziesięciu atomów stają się niewiarygodne. W Claude Code łączny budżet po kompresji stanowi sztywny limit, a inne agenty mają swoje własne ograniczenia. Trzymaj molekuły w granicach od dwóch do dziesięciu atomów i umieszczaj kluczowe kroki na wczesnym etapie.
  • Związki składające się z od ośmiu do dziesięciu molekuł również napotykają swoje ograniczenia. Orkiestrator musi śledzić, które podagenty zakończyły pracę, co wytworzyły oraz co następuje dalej; po przekroczeniu określonej wielkości traci kontekst. Podziel większy związek na dwa, umieszczając między nimi kontrolny punkt wykonany przez człowieka.
  • Automaticzne wywoływanie jest mniej niezawodne niż wywoływanie ręczne. Oceny agentów opublikowane przez Vercel pokazały, że w dużej liczbie przypadków testowych umiejętności nie były wykorzystywane, a ten wzorzec prawdopodobnie występuje również poza Claude Code. Jest to do przyjęcia w przypadku atomów. W przypadku molekuł i związków wyłącz automatyczne wywoływanie i uruchamiaj je osobiście.

Jesteś kierowcą, a agent to silnik.

Dlaczego to ważne

Niedobrym zasobem nie są obliczenia ani tokeny, lecz twoja uwaga. Wpisanie „sprawdź ten e-mail” oraz „wykonaj zapytanie do segmentu fintech” wymaga mniej więcej tyle samo wysiłku umysłowego przy rozpoczynaniu i monitorowaniu, a mimo to wyniki różnią się o kilka rzędów wielkości.

Krótko mówiąc, atomy dostarczają agentowi przewidywalnych jednostek pracy, molekuły łączą te jednostki w sekwencje, które coś osiągają, natomiast związki uruchamiają kilka sekwencji równocześnie w oddzielnych oknach kontekstowych. Każdy poziom zwiększa ilość wyników, podczas gdy twoja uwaga pozostaje w przybliżeniu stała.

Taka architektura jest już wspierana – wyraźnie w Claude Code oraz za pomocą równoważnych konstrukcji w innych narzędziach. To właśnie wzorzec kompozycji jest tym, czego większość programistów jeszcze nie stworzyła.

Dokumentacja umiejętności Claude Code znajduje się pod adresem code.claude.com/docs/en/skills, a format SKILL.md odpowiada otwartemu standardowi Agent Skills, który jest używany w różnych narzędziach AI. Proponowanym wzorem są atomy, cząsteczki i związki chemiczne, a pokazany kod to pseudokod służący do wyjaśnienia tych koncepcji.