Практические заметки: Проектирование циклов с использованием агентов
Пошаговое руководство по практическим советам: проектирование циклов с использованием агентов: контракты, проверки и слоты для вставки кода для команд, использующих эту модель.
Используйте это как переработанную версию идей из книги «Инженерия циклов с агентами», ориентированную на операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задач. Этап обзора работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте как успешный путь выполнения, так и путь восстановления одновременно. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не последующими доработками.
Оглавление
На этапе создания оглавления необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не пытаясь угадать скрытое состояние системы. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных. Внедрять человеческое утверждение для операций, связанных с расходованием средств или изменением производственных данных. Простая настройка во время компиляции не гарантирует полноты реализации бизнес-логики.
1. Структура агентного цикла
На первом этапе «Анатомия» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты выполнения бизнес-задач.
2. Когда использовать инженерию циклов
На этапе «Когда использовать» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Внедряйте человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты функционала продукта. На этапе «Когда использовать» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно «идеальный путь» и пути восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.
3. Распространённые типы циклов
При работе с 3 распространёнными типами циклов сначала запишите условия их работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет избежать ошибок при последующих изменениях кода. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое какого-либо шага причина неудачи должна быть связана с конкретной функцией, а не с запутанной последовательностью операций. Вносите контрольные точки после дорогостоящих шагов. Система не должна повторно оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
+-----------+ +-----------+
-->| Generate |----->| Verify |----- pass -----> [ done ]
+-----------+ +-----+-----+
^ |
+------- fail ------+
+-----------+ +-----------+
-->| Generate |----->| Score |--- good enough --> [ done ]
+-----------+ +-----+-----+
^ |
+-- improve --------+
(use the score)
+-----------+ +-----------+
-->| Plan |----->| Execute |-- all steps done --> [ done ]
+-----------+ +-----+-----+
^ |
+-- replan ---------+
(hit a surprise)
+-----------+ +-----------+ +-----------+
-->| Wait |---->| Check |---->| Act |---+
| (timer / | +-----------+ +-----------+ |
| trigger) | |
+-----------+ <-------------------------------------+
(no fixed end — keeps watching over time)
4. Как создать цикл
При работе над этапом «4 способа построения» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым элементам, определите критерии успешности и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
+------------------+
START ----------> | Research | <-------------+
| (draft / revise) | |
+--------+---------+ |
| |
v | needs work
+------------------+ | (+ feedback)
| Verify | |
| (check claims) | |
+--------+---------+ |
| |
v |
+-----------+ needs work |
| Decide |-------------------+
| (router) |
+-----+-----+
| verified / out of tries
v
[ END ]
pip install langgraph==1.2.6 langchain-openai==1.3.3 pydantic==2.13.4
export OPENAI_API_KEY="your-key-here"
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
# A model client on OpenAI's Responses API, with the built-in web-search tool
# bound on — so the model can search the web itself, no extra package needed.
# "gpt-5" is a reasoning model; swap it for any current model you have access to.
llm = ChatOpenAI(model="gpt-5", use_responses_api=True)
searcher = llm.bind_tools([{"type": "web_search"}])
MAX_ITERATIONS = 3 # a stop rule, decided up front
# STATE — the shared memory passed between every node
class ResearchState(TypedDict):
question: str # what we're answering
draft: str # the current best answer
verdict: str # "verified" or "needs_work"
feedback: str # what the verifier said to fix
iterations: int # how many times we've looped
# The verifier returns a typed result, so the router gets a clean
# "verified" / "needs_work" to branch on instead of parsing prose.
class Verdict(BaseModel):
status: str = Field(description='"verified" or "needs_work"')
feedback: str = Field(description="claims lacking support, if any")
# NODE 1 — the maker: search the web, then draft (or revise) the answer.
def research(state: ResearchState) -> dict:
prompt = "Search the web, then answer the question. Back every claim with a source.\n"
if state.get("feedback"):
prompt += f"A reviewer flagged these gaps — fix them:\n{state['feedback']}\n"
prompt += f"\nQuestion: {state['question']}"
draft = searcher.invoke(prompt).text
return {"draft": draft, "iterations": state["iterations"] + 1}
# NODE 2 — the checker: search for evidence, then critique the draft.
def verify(state: ResearchState) -> dict:
evidence = searcher.invoke(
f"Search the web for evidence to fact-check claims about: {state['question']}"
).text
checker = llm.with_structured_output(Verdict)
result = checker.invoke(
"You are a fact-checker. Using the evidence below, reply 'verified' "
"only if every claim in the answer is supported; otherwise 'needs_work' "
"and list the unsupported claims as feedback.\n\n"
f"Evidence:\n{evidence}\n\nAnswer:\n{state['draft']}"
)
return {"verdict": result.status, "feedback": result.feedback}
# ROUTER — the heart of the loop. Reads the verdict, picks the next step.
def decide(state: ResearchState) -> Literal["research", "__end__"]:
if state["verdict"] == "verified":
return "__end__" # success: goal met
if state["iterations"] >= MAX_ITERATIONS:
return "__end__" # surrender: out of tries
return "research" # loop back and fix the gaps
# WIRE IT UP
graph = StateGraph(ResearchState)
graph.add_node("research", research)
graph.add_node("verify", verify)
graph.add_edge(START, "research") # trigger
graph.add_edge("research", "verify") # always verify a fresh draft
graph.add_conditional_edges("verify", decide, {
"research": "research", # the backward arrow = the loop
"__end__": END,
})
agent = graph.compile()
result = agent.invoke({
"question": "What were the main causes of the 2008 financial crisis?",
"draft": "", "verdict": "", "feedback": "", "iterations": 0,
})
print(result["draft"])
5. Виды сбоев и меры предотвращения
При работе над этапом «5 защитных механизмов от сбоев» сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичном сбое. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Запишите также время выполнения операций, стоимость токенов или запросов рядом с результатами их работы. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Система должна не повторно взимать плату за один и тот же вызов большой языковой модели при повторной попытке обработки задачи. При работе над этапом «5 защитных механизмов от сбоев» сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичном сбое. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный пути работы системы. Повторные попытки, проверки со стороны оператора и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.
6. Когда НЕ следует использовать технику циклической разработки
Инструкция «6 ситуаций, когда не стоит выполнять задачу» наилучшим образом работает, если рассматривать её как измеримую структуру. Соберите один идеальный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда происходит сбой на каком-либо этапе, он должен указывать на конкретную ответственность, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
Заключение
Этап заключения работает наилучшим образом, если рассматривать его как измеримую структуру. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия всем элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
Ссылки
Этап «Справочные материалы» работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и могут нарушить возобновление работы после прерываний. Этап «Справочные материалы» работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию до расширения объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Чек-лист операций
При работе над этапом операционного чек-листа сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода.
Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код.
Создавайте точки контроля после дорогостоящих операций. Система возобновления выполнения не должна снова взимать плату за один и тот же вызов большой языковой модели при повторной попытке обработки последующего элемента.
Фиксируйте версии зависимостей и записывайте хэш изображения, с использованием которого выполнялась демонстрация. Воспроизводимость важнее устного опыта команды.
Документируйте как успешный, так и путь восстановления. Повторные попытки, проверки человеком и обработка ошибок являются неотъемлемой частью продукта, а не дополнительными улучшениями.
Пункт контроля после дорогостоящих операций. Система возобновления не должна снова взимать плату за один и тот же вызов LLM, когда оператор пытается выполнить задачу в более позднем этапе.
Перед повышением уровня стека необходимо заморозить версии, сохранить эталонный отчет для критического пути и уточнить шаги возврата к предыдущему состоянию. В совместных средах требуются ограничения на частоту запросов, проверки принадлежности ресурсов и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.
Примечание для пакета 5e9b984e8d8a: не храните ключи поставщика в репозитории, установите лимит токенов на каждую сессию и сохраняйте отчеты рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.
На этом этапе усиления безопасности работа будет наилучшей, если рассматривать поверхность как измеримый объект. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задач.
Подробности усиления безопасности 0/884: измерьте время выполнения, класс ошибки и количество использованных токенов для этой записи, затем решите, следует ли сохранять изменения, опираясь на заранее установленный набор критериев, а не на единичные примеры.
Для первого этапа усиления безопасности необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Конфигурацию следует хранить отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф.
Подробности усиления безопасности 1/884: измеряйте время выполнения, класс ошибок и расход токенов для данного шага, затем принимайте решение о сохранении изменений на основе заранее определенного набора критериев, а не на основе устных оценок.
При работе над вторым этапом записки по усилению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
Деталь усиления безопасности 2/884: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение, опираясь на фиксированный набор критериев, а не на устные оценки.
Второй этап записки по усилению безопасности работает наилучшим образом, когда его рассматривают как измеряемую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
Подробности усиления безопасности 3/884: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
На четвертом этапе работы над усилием безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте как успешный, так и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями.
Подробности усиления безопасности 4/884: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
При работе над этапом 5 записки по усилению безопасности сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия соответствующим элементам, определите критерии успешности и не допускайте молчаливого частичного выполнения задач.
Подробности усиления безопасности 5/884: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе единичных примеров.
Этап 6 записки по усилению безопасности работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код.
Подробности усиления безопасности 6/884: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
На этапе 7 записи о усилении безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочтительнее использовать небольшие, проверяемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на запутанную структуру обработки данных.
Подробности усиления безопасности 7/884: измерьте время выполнения, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
При работе над этапом 8 записки по усилению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения, стоимость токенов или запросов. Очевидность затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
Подробности усиления безопасности 8/884: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе устных оценок.
Этап 9 записки по усилению безопасности лучше всего работает, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Подробности усиления безопасности 9/884: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
На этапе 10 процедуры усиления безопасности определите входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безответственного частичного завершения работы.
Подробности усиления безопасности 10/884: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
При работе над этапом усиления безопасности №11 сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код.
Подробности усиления безопасности 11/884: измеряйте время выполнения, класс ошибок и расход токенов для данного этапа, затем принимайте решение о сохранении изменений на основе определенного набора критериев, а не на основе устных оценок.