Практические замечания: почему навыки ИИ-агента нарушаются при их объединении в цепочку и что с этим делать
Пошаговое руководство по практическим заметкам: почему навыки ИИ-агентов теряют эффективность при их объединении в цепочки, а также контракты, проверки и готовые блоки кода для команд, использующих эту схему.
В следующих заметках описывается практический подход к решению проблемы, связанной с нарушением работы навыков ИИ-агентов при их объединении, а также предлагается трехуровневое решение. Основное внимание уделяется контрактам, проверкам и шаблонам кода, а не мотивационным аспектам. На этапе обзора сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные расходы при переходе от демо-версии к общедоступным средам.
Три уровня, соответствующих реальному способу составления агентов
Три уровня, соответствующие этапам, работают наилучшим образом, когда рассматриваются как измеримая структура. Соберите один образец успешного выполнения, один пример сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
Атомы: отдельные навыки, выполняющие одну функцию
На этапе «Атомы: отдельные навыки» лучше всего работать, рассматривая его как измеримую структуру. Соберите один пример успешного выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно путь успешного выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и нарушают возможность продолжения работы после прерываний.
---
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.
Молекулы: явные цепи атомов
Molecules Explicit Chains of stage работает наилучшим образом, когда его рассматривают как измеримую поверхность. Сохраняйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Предпочитайте небольшие, тестируемые единицы вместо обширных скриптов. При сбое какого-либо шага причина должна указывать на конкретный элемент ответственности, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний. Molecules Explicit Chains of stage работает наилучшим образом, когда его рассматривают как измеримую поверхность. Сохраняйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
---
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
Соединения: оркестрация подагентов
На этапе оркестрации действий агентов для сложных компонентов необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища конфиденциальных данных и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Для операций, связанных с тратой денег или изменением производственных данных, необходимо предусмотреть утверждение человеком. Подключения, созданные во время компиляции, не гарантируют полноты охвата бизнес-логики.
---
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
Структура папок
На этапе структуры папок необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо задокументировать как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Внедрять утверждение человеком для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты функционала продукта.
.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
Тот же паттерн в других фреймворках
Для реализации одинаковой схемы на данном этапе необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг, исходя из известной точки контроля, без необходимости угадывать скрытое состояние. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой процессов. Внедрять человеческое утверждение для операций, связанных с расходованием средств или изменением производственных данных. Простая настройка во время компиляции не гарантирует полноты функционала системы. Для реализации одинаковой схемы на данном этапе необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг, исходя из известной точки контроля, без необходимости угадывать скрытое состояние. Регистрировать время выполнения, а также стоимость токенов или запросов вместе с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.
LangGraph: Инструменты → Цепочки → Подграфы
При работе с этапом «Цепочки инструментов — Подграфы» в LangGraph сначала запишите спецификацию: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет избежать ошибок при последующих изменениях кода. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Фиксируйте название инструмента, хэш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агента занимает часы.
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: Инструменты → Задачи → Команды в потоках
При работе над этапом Crews в инструментах CrewAI Tools сначала запишите условия работы: необходимые входные данные, сигнал успешного завершения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агента занимает часы.
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
При работе с этапом Agent Teams инструмента Agno сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка циклов агента занимает много времени. При работе с этапом Agent Teams инструмента Agno сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Регистрируйте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
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.",
)
Шаблон остается прежним
Этот шаблон работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один пример успешной работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работы. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая всю структуру. Сохраняйте состояние структуры простым и типизированным. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению возобновления работы после перерывов.
Где это ломается сегодня
Этап «Где происходит сбой сегодня» работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный и восстановительный пути. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не последующими улучшениями. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и мешают возобновлению работы после прерываний.
Атомы, которые не являются твёрдыми, разрушают всё, что находится над ними:
Алгоритм Atoms that aren’t stage работает наилучшим образом, когда его рассматривают как измеримую структуру. Сохраняйте один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма задачи. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной ответственностью, а не с запутанной цепочкой операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению работоспособности после перерывов. Алгоритм Atoms that aren’t stage работает наилучшим образом, когда его рассматривают как измеримую структуру. Сохраняйте один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма задачи. Записывайте временные показатели, а также стоимость обработки токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
Молекулы, состоящие из более 10 атомов, становятся ненадёжными:
Для молекул, содержащих более 10 атомов, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища конфиденциальных данных и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Для операций, связанных с тратой денег или изменением производственных данных, необходимо предусмотреть утверждение человеком. Подключения, созданные во время компиляции, не гарантируют полноты охвата бизнес-процессов.
Соединения, содержащие более 8–10 молекул, сталкиваются со своими ограничениями:
Для процессов, находящихся за 8–10 этапами, необходимо заранее определить входные данные, ответственного за выполнение этапа и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить этап с известной точки контроля, не догадываясь о скрытом состоянии системы. Необходимо документировать как успешный, так и аварийный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Внедрять утверждение человеком для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты функционала продукта.
Автоматическое вызовы менее надежны, чем явные вызовы:
На этапе, где автоматическое вызовы менее надежны, необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную цепочку операций. Внедрять человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты бизнес-логики. На этапе, где автоматическое вызовы менее надежны, необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения, а также стоимость токенов или запросов вместе с функциональными результатами. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-режима к
общие среды.Почему это важно
На этапе анализа важности сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
Чек-лист операционной деятельности
На этапе составления чек-листа операционной деятельности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг, используя известную контрольную точку, без необходимости угадывать скрытое состояние.
Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не соглашайтесь на молчаливое частичное выполнение задачи.
Обеспечьте человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты решения в бизнес-среде.
Напишите краткий руководство: как обновлять ключи, как опустошать очередь, как откатить последнюю загрузку данных.
Записывайте время выполнения операций, а также стоимость токенов или запросов рядом с функциональными результатами. Ясность стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам.
Обеспечьте человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты решения в бизнес-среде.
Перед внедрением данной стек-технологии необходимо заморозить версии, сохранить эталонный отчет для критической цепочки операций и уточнить шаги возврата к предыдущему состоянию. В совместных средах требуются ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, даже если она кажется менее привлекательной, чем красивые одноразовые демонстрации.
Примечание к заданию 373492c8b420: не храните ключи поставщика в репозитории, установите лимит токенов на одну сессию и сохраняйте отчеты рядом с фиксами для оценки, чтобы позже можно было сравнивать результаты работы разных моделей.