Wskazówki praktyczne: Dlaczego umiejętności agentów AI przestają działać, gdy łączymy je ze sobą i
Krok po kroku praktyczne wskazówki: dlaczego umiejętności agentów AI przestają działać, gdy je łączymy, oraz umowy, sprawdzenia i gotowe elementy kodu dla zespołów wdrażających ten wzorzec.
Poniższe notatki przedstawiają praktyczne podejście do tematu „Dlaczego umiejętności agentów AI przestają działać, gdy je łączymy, oraz rozwiązanie w trzech etapach”. Nacisk kładziony jest na umowy, sprawdzania oraz miejsca zastępcze dla kodu, a nie na motywacyjne aspekty. Podczas przechodzenia przez etap przeglądu najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisz czas wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy przechodzi się od demonstracji do wspólnych środowisk.
Trzy poziomy odpowiadające sposobowi, w jaki faktycznie komponują się agenci
Trzy poziomy odpowiadające fazom działania najlepiej funkcjonują, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden „złoty” przepis, jeden przypadek awarii oraz notatkę o cofnięciu zmian, zanim rozszerzysz zakres pracy. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Utrzymuj stan struktury w formie prostych, typizowanych elementów. Wplecione bloki danych ukrywają informację o tym, który węzeł zapisał dane do którego pola, co powoduje przerwanie kontynuacji działania po zakłóceniach.
Atomy: pojedyncze umiejętności pełniące jedną funkcję
Na etapie Atoms Single Skills najlepiej postępować tak, jakby chodziło o mierzalną powierzchnię. Zapisz jeden idealny przypadek, jeden przypadek niepowodzenia oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zdokumentuj zarówno ścieżkę pomyślnego przebiegu, jak i ścieżkę przywracania stanu. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, i powodują przerwanie kontynuacji po przerwach.
---
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.
Molekuły: Wyraźne łańcuchy atomów
Molecules Explicit Chains of stage funkcjonuje najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wtórne struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, co powoduje przerwę w kontynuacji działania po zakłóceniach. Molecules Explicit Chains of stage funkcjonuje najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden idealny przepis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych.
---
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
Związki chemiczne: Orkiestracja podagentów
W fazie orkiestracji podagentów związków należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zastosuj ludzką aprobatę dla połączeń, które powodują wydatki lub zmieniają dane produkcyjne. Połączenia ustalane w czasie kompilacji nie równają się pełności funkcjonalności biznesowej.
---
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
Struktura folderów
W fazie struktury folderów należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Konieczne jest ludzkie zatwierdzenie w przypadkach, gdy dochodzi do wydawania pieniędzy lub zmiany danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się kompletności rozwiązania biznesowego.
.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
To samo wzorzec w innych frameworkach
Dla tego samego wzorca na danej fazie należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Konieczne jest ludzkie zatwierdzenie w przypadkach, gdy dochodzi do wydatków lub zmian w danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie równają się pełnej kompletności biznesowej. Dla tego samego wzorca na danej fazie należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do wspólnych środowisk.
LangGraph: Narzędzia → Łańcuchy → Podgrafy
Gdy pracujesz na etapie Łańcuchów Narzędzi Podgrafów w LangGraph, najpierw zapisz specyfikację: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całego grafu. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdej wywołania. Bez takich informacji debugowanie pętli agenta trwa godzinami.
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)
CrewAI: Narzędzia → Zadania → Zespoły w przepływach
Gdy pracujesz nad etapem zadań CrewAI Tools Tasks Crews, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno prawidłowy przebieg, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez człowieka oraz obsługa wiadomości błędowych są częścią produktu, a nie elementem późniejszej dopracowywania. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Bez takich informacji debugowanie pętli agenta marnuje godziny.
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
Agno: @tool → Agent → Teams
Gdy pracujesz nad etapem Agent Teams w narzędziu Agno, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok się nie powiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Zapisuj nazwę narzędzia, hash argumentów, opóźnienie oraz wynik każdego wywołania. Debugowanie pętli agenta bez takich informacji marnuje godziny. Gdy pracujesz nad etapem Agent Teams w narzędziu Agno, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do wspólnych środowisk.
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.",
)
Wzorzec jest taki sam
Wzorzec funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden przykład udanego działania, jeden przypadek awarii oraz notatkę o cofnięciu zmian, zanim rozszerzysz zakres. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny poufnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Utrzymuj stan struktury w prostym formacie i z określonym typem danych. Wplecione elementy ukrywają informację o tym, który węzeł zapisał dane do którego pola, co powoduje przerwania w kontynuacji działania po zakłóceniach.
Gdzie to obecnie zawodzi
Etap „Where It Breaks Today” funkcjonuje najlepiej, gdy traktowany jest jako mierzalna powierzchnia. Zapisz jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres badania. Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę przywracania do normalnego stanu. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości nieodebranych stanowią część produktu, a nie elementy dodawane później w celu udoskonalenia. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wplecione struktury ukrywają informację o tym, który węzeł zapisał dane w danym polu, co powoduje przerwanie kontynuacji działania po zakłóceniach.
Atomy, które nie są stałe, niszczą wszystko nad nimi:
The Atoms that aren’t stage funkcjonuje najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj stan grafu w prostej formie i z określonym typem danych. Wtórne struktury ukrywają informację o tym, który węzeł zapisał dane do którego pola, co utrudnia kontynuację pracy po przerwach. The Atoms that aren’t stage funkcjonuje najlepiej, gdy traktuje się je jako mierzalną powierzchnię. Zapisz jeden idealny zapis działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zapisuj czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy ścieżka przechodzi z wersji demonstracyjnej do środowisk współdzielonych.
Cząsteczki składające się z ponad 10 atomów stają się niepewne:
Dla związków chemicznych składających się ze więcej niż 10 atomów należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany etap oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten etap na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny poufnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Zatwierdzenie przez człowieka powinno być wymagane dla operacji, które wiążą się z wydawaniem pieniędzy lub modyfikacją danych produkcyjnych. Połączenia ustalone w czasie kompilacji nie równają się pełnej kompletności biznesowej.
Związki chemiczne składające się z więcej niż 8–10 cząsteczek napotykają swoje własne ograniczenia:
Dla złożeń po etapie 8 lub 10 należy określić dane wejściowe, osobę odpowiedzialną za dany etap oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten etap na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżki naprawcze. Próby ponownych działań, kontrola przez ludzi oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Konieczna jest ludzka akceptacja w przypadku operacji, które powodują wydatki lub zmieniają dane produkcyjne. Podłączenia realizowane w czasie kompilacji nie równają się kompletności rozwiązania biznesowego.
Autoryzowane wywołanie jest mniej niezawodne niż wywołanie jawne:
W fazie, w której automatyczne wywoływanie jest mniej niezawodne, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, powinien wskazywać na konkretną przyczynę, a nie na skomplikowaną strukturę procesu. Konieczne jest ludzkie zatwierdzenie w przypadkach, gdy dochodzi do wydatków lub zmian w danych produkcyjnych. Połączenia realizowane w czasie kompilacji nie gwarantują pełnej kompletności biznesowej. W fazie, w której automatyczne wywoływanie jest mniej niezawodne, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy proces przechodzi z wersji demonstracyjnej do
środowiska współdzielone.Dlaczego to ma znaczenie
Podczas przechodzenia przez etap „Dlaczego to ma znaczenie”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Ustal punkty kontrolne po kosztownych krokach. System powinien unikać ponownego pobierania opłat za tę samą operację LLM, gdy operator próbuje ponownie wykonać późniejszy krok.
W etapie listy kontrolnej operacyjnej zdefiniuj dane wejściowe, osobę odpowiedzialną za krok oraz kryteria zakończenia przed dokonaniem zmian w kodzie. Operatorzy powinni móc ponownie wykonać krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Rozpatruj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania.
Zapewnij ludzką aprobatę dla operacji, które powodują wydanie pieniędzy lub zmianę danych produkcyjnych. Połączenia skompilowane w czasie kompilacji nie równają się pełnej kompletności procesu biznesowego.
Napisz krótki przewodnik: jak rotować klucze, jak opróżniać kolejki z zadań, jak cofnąć ostatni proces pobierania danych.
Zapisz czasy wykonywania zadań oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Zapewnij ludzką aprobatę dla operacji, które powodują wydanie pieniędzy lub zmianę danych produkcyjnych. Połączenia skompilowane w czasie kompilacji nie równają się pełnej kompletności procesu biznesowego.
Zanim zaczniesz promować tę architekturę, zamroź wersje, utwórz dokładny zapis dla kluczowych etapów realizacji oraz potwierdź kroki odwracania zmian. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji przynależności użytkowników oraz wyraźnego właściciela odpowiedzialnego za rotację haseł. Wolimy nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Uwaga dotycząca zlecenia 373492c8b420: unikaj przechowywania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj zapisy obok plików testowych, aby późniejsze zmiany modeli pozostawały porównywalne.