Урок 11.5. Agent Runtime Frameworks

Зачем это нужно

В модуле Multi-Agent Development мы разобрали роли, independent review и orchestration как engineering protocol. Теперь нужно отделить этот протокол от специальных frameworks, с помощью которых можно программировать собственные agent systems.

До этого момента курс в основном работал с coding agents:

Developer
-> Coding agent
-> Repository
-> Tests
-> Review

Agent runtime framework нужен в другом случае:

Developer builds product
-> Product contains agents
-> Agents call tools, hand off work, store state, produce traces

Главная цель урока - объяснить, когда достаточно coding agent workflow, а когда действительно пора выбирать OpenAI Agents SDK, LangGraph, AutoGen, CrewAI или похожий runtime.

Основная идея

Coding agent harness помогает вам менять код.

Agent runtime framework помогает вашему продукту выполнять agentic workflow.

Это разные уровни:

Coding Agent Harness:
    "Помоги разработчику реализовать feature в repository."

Agent Runtime Framework:
    "Внутри моего продукта есть agents, tools, state и handoffs."

Если вы делаете password reset endpoint, runtime framework почти наверняка не нужен.

Если вы строите сервис, который принимает ticket, классифицирует проблему, вызывает tools, передает задачу reviewer agent и сохраняет trace, runtime framework уже может быть оправдан.

Ключевые термины

Термин	Значение
Agent Runtime	Исполняющая среда для agent workflow: model calls, tools, state, handoffs, guardrails, tracing.
Agent	Компонент с instructions, model, tools и ожидаемым output contract.
Tool	Действие, которое agent может вызвать: API, search, database query, script, MCP tool.
Handoff	Передача задачи от одного agent или stage к другому.
State	Данные процесса, которые сохраняются между шагами workflow.
Graph	Явная модель переходов между nodes/stages.
Team	Группа agents, которые обмениваются messages и совместно решают задачу.
Termination Condition	Правило остановки agent interaction.
Guardrail	Проверка или ограничение, которое предотвращает небезопасный output/action.
Trace	Запись agent run: шаги, tools, decisions, latency, errors, cost.

Почему нельзя начинать с runtime framework

Agent runtime framework добавляет новые moving parts:

state management;
tool permissions;
retry policy;
orchestration logic;
observability;
deployment;
security boundaries;
evals;
human gates.

Если у команды еще нет specs, tests, CI и Git discipline, runtime framework не решит эту проблему. Он только сделает failure modes сложнее.

Базовое правило курса:

Сначала controlled single-agent development.
Потом multi-agent protocol.
Только потом custom runtime.

Основные primitives runtime frameworks

Большинство agent runtimes так или иначе оперируют похожими сущностями.

flowchart TD A[Input] --> B[Agent instructions] B --> C[Model call] C --> D{Need tool?} D -->|yes| E[Tool call] E --> F[Tool result] F --> C D -->|no| G[Output] G --> H[Guardrail] H -->|pass| I[Next stage / user] H -->|fail| J[Retry / handoff / human gate] C --> K[Trace] E --> K H --> K

Ключевой вопрос выбора framework:

Какая часть этой схемы для вас самая сложная?

Если сложнее всего tools и handoffs, нужен один тип framework.

Если сложнее всего state machine, нужен другой.

Если сложнее всего conversation между agents, нужен третий.

OpenAI Agents SDK

В исходном плане курса OpenAI Agents SDK описан через primitives:

Agent
Tools
Handoffs
Guardrails
Sessions
Tracing
MCP

Архитектурно это удобно, когда нужно собрать agent workflow поверх OpenAI ecosystem и явно описать:

кто такой agent;
какие instructions у него есть;
какие tools разрешены;
какие outputs допустимы;
куда можно передавать задачу;
какие guardrails применяются;
как видеть trace.

Когда подходит

нужно быстро сделать production-oriented agent workflow;
важно иметь tools, handoffs и guardrails в одной модели;
проект уже использует OpenAI stack;
нужно аккуратно встроить MCP tools;
observability agent runs важна с первого дня.

Когда может быть лишним

задача заключается только в изменении repository через coding agent;
нет собственного agentic продукта;
достаточно scripts, tests и manual review;
workflow простой и не требует runtime state.

LangGraph

LangGraph полезно рассматривать как graph/state-machine подход к agent workflows.

Типичная ментальная модель:

START
-> Planner
-> Tool node
-> Check
-> Retry or END

Главная сила такого подхода - explicit control flow. Вы не просто надеетесь, что agent "сам разберется", а описываете nodes, edges, state и условия перехода.

Когда подходит

workflow должен быть воспроизводимым;
важен persistent state;
есть human-in-the-loop stages;
нужны retry branches;
нужно смешать deterministic logic и model calls;
требуется точная orchestration.

Пример

Ticket received
-> Classify
-> Retrieve customer data
-> Draft response
-> Policy check
-> Human approval if risky
-> Send response
-> Store trace

Такой workflow удобнее держать в graph, чем в одном длинном prompt.

Риск

LangGraph-подход требует больше инженерной дисциплины:

нужно проектировать state;
нужно тестировать nodes;
нужно думать о retries;
нужно сохранять trace;
нужно объяснять graph команде.

AutoGen

AutoGen в исходном плане полезен как пример framework, где центральна multi-agent communication.

Ключевые идеи:

agents;
teams;
messages;
termination conditions;
shared или передаваемый state;
human-in-the-loop.

Когда подходит

несколько agents должны обсуждать задачу;
interaction pattern важнее жесткой state machine;
нужно моделировать роли: planner, critic, engineer, reviewer;
task решается через обмен messages;
важно контролировать, когда conversation должна завершиться.

Пример

Planner agent proposes migration plan.
Database reviewer challenges risk.
Backend agent proposes API change.
Security reviewer checks permissions.
Manager agent ends discussion when acceptance criteria covered.

Для курса важно помнить: conversation сама по себе не гарантирует качество. Нужны termination conditions, role boundaries и external verification.

CrewAI

CrewAI удобно объяснять через role-oriented модель:

Agent
Task
Crew
Flow

Crew объединяет agents вокруг набора задач, а Flow позволяет строить workflow с branching и state.

Когда подходит

команда хочет думать в терминах ролей;
workflow понятнее как "кто что делает";
задачи можно описать явно;
нужна более простая входная модель, чем низкоуровневый graph;
важны роли, responsibilities и handoffs.

Пример

Crew:
- Product Analyst
- Backend Engineer
- Test Engineer
- Reviewer

Tasks:
- clarify requirements
- design API
- draft tests
- review implementation

В production это все равно должно быть связано с specs, tests, guardrails и logs.

Сравнение frameworks

Framework	Главная abstraction	Когда выбирать
OpenAI Agents SDK	Agents, tools, handoffs, guardrails, tracing	Нужен production-oriented agent workflow в OpenAI ecosystem.
LangGraph	Graph, state, nodes, edges	Нужен точный control flow, persistent state, retries, human gates.
AutoGen	Agents, teams, messages	Нужна multi-agent communication как центральный механизм.
CrewAI	Agents, tasks, crews, flows	Нужна role-oriented модель с понятным workflow.

Еще проще:

Простой agent workflow
-> Agents SDK

Сложная state machine
-> LangGraph

Agent conversation / teams
-> AutoGen

Ролевая команда agents
-> CrewAI

Это не абсолютное правило, а стартовая heuristic.

Как понять, что runtime framework уже нужен

Runtime framework оправдан, если есть хотя бы несколько признаков:

agentic workflow является частью продукта, а не только процесса разработки;
нужны persistent sessions или state;
есть несколько tools с permissions;
нужно несколько agent roles;
есть handoffs;
нужны guardrails на output/action;
нужно tracing для каждой операции;
есть human-in-the-loop stages;
нужны evals runtime behavior;
workflow будет запускаться много раз, а не один раз вручную.

Если этих признаков нет, начните с меньшего:

spec.md
tasks.md
coding agent
scripts/verify
CI
review

Пример для capstone. Notifications triage agent

В SaaS Task Manager есть notifications subsystem. На базовом уровне это обычная feature:

user receives notification;
email sent on task assignment;
audit log records delivery attempt;
retry policy defined.

Для этого runtime framework не нужен. Достаточно specs, tasks, tests и agent development loop.

Но представим расширение:

Система анализирует failed notifications,
определяет root cause,
вызывает tools для проверки provider status,
создает internal incident,
предлагает mitigation,
и отправляет отчет человеку.

Это уже agentic subsystem.

Возможная runtime architecture

flowchart TD A[Failed notification event] --> B[Classifier Agent] B --> C{Failure type} C -->|Provider| D[Provider Status Tool] C -->|Bad address| E[User Data Tool] C -->|Template| F[Template Check Tool] D --> G[Incident Draft Agent] E --> G F --> G G --> H[Policy Guardrail] H -->|low risk| I[Create incident] H -->|high risk| J[Human approval] J --> I I --> K[Trace and eval sample]

Здесь runtime framework полезен, потому что нужно:

хранить state incident investigation;
вызывать tools;
обрабатывать branches;
делать human gate;
сохранять trace;
тестировать agent behavior evals.

Runtime и MCP

MCP может быть частью runtime architecture, но это не одно и то же.

Сущность	Роль
Runtime framework	Управляет agent workflow, state, handoffs, guardrails, tracing.
MCP server	Предоставляет tools, resources и prompts внешней системе.
Tool	Выполняет конкретное действие или читает данные.
Skill	Описывает процедуру, как агенту выполнять повторяемую задачу.

Пример:

Runtime: LangGraph workflow
MCP: GitHub server
Tool: read_pull_request
Skill: review-code procedure
Guardrail: no approval on security-critical PR without human

Runtime и evals

Для agent runtime тестов кода недостаточно.

Нужно проверять:

выбирает ли agent правильный tool;
не вызывает ли destructive tool без approval;
корректно ли завершает workflow;
соблюдает ли output schema;
передает ли задачу другому agent в нужный момент;
не уходит ли в бесконечный loop;
сохраняет ли trace.

Пример eval scenario:

Input:
Failed notification event with provider timeout.

Expected behavior:
- classify as provider issue
- call provider status tool
- create incident draft
- do not email customer directly
- include evidence from tool result
- mark run as needs-human-review if provider outage affects many users

Это уже eval of agent behavior, а не обычный unit test.

Типичные ошибки

Ошибка 1. Использовать runtime framework вместо хорошего spec

Framework не знает, что такое правильное product behavior. Это знает spec.

Ошибка 2. Делать каждого helper отдельным agent

Если задача детерминированная, нужен function, script или service. Не нужно превращать простую проверку в agent.

Плохо:

Formatter Agent

Лучше:

npm run format

Ошибка 3. Не проектировать termination conditions

Multi-agent conversation без правила остановки может жечь budget и не приближать acceptance.

Хорошее правило:

Stop when all acceptance criteria are mapped to tests
or when unresolved product decision requires human approval.

Ошибка 4. Давать runtime tools без permissions

Agent с access к billing, production data или destructive operations должен работать через strict permissions и human gates.

Ошибка 5. Не логировать agent runs

Если нет trace, невозможно ответить:

почему agent выбрал tool;
где возник retry;
какие данные он видел;
почему guardrail пропустил output;
какой eval должен появиться после failure.

Checklist перед выбором runtime

[ ] У нас есть approved specification.
[ ] Workflow повторяется много раз.
[ ] Есть state или sessions.
[ ] Есть tools с permissions.
[ ] Есть branches/retries/handoffs.
[ ] Есть human gates для high-risk cases.
[ ] Есть tracing/logging.
[ ] Есть eval scenarios.
[ ] Есть rollback или safe failure mode.
[ ] Команда понимает, почему scripts/CI/coding agent недостаточно.

Если большинство пунктов не отмечено, runtime framework пока преждевременен.

Критерии готовности

После урока студент должен уметь:

объяснить отличие coding agent harness от agent runtime framework;
назвать базовые primitives runtime: agent, tool, handoff, state, guardrail, trace;
выбрать между OpenAI Agents SDK, LangGraph, AutoGen и CrewAI на уровне задачи;
понять, когда runtime framework будет лишним;
связать runtime с MCP, skills, tests и evals;
описать human-in-the-loop gates для agentic workflow.

Краткое резюме

Agent runtime framework нужен, когда agentic behavior становится частью продукта. Для обычной разработки фичи в repository чаще достаточно specs, tasks, coding agent, tests, Git и review.

OpenAI Agents SDK удобен для agent workflow с tools, handoffs, guardrails и tracing. LangGraph подходит для explicit graph/state machine. AutoGen полезен для multi-agent communication. CrewAI удобен для role-oriented teams и tasks.

Главное правило: runtime framework должен решать реальную orchestration проблему, а не заменять дисциплину specifications, tests и human gates.

Вопросы для самопроверки

Чем coding agent harness отличается от agent runtime framework?
Когда LangGraph-подход лучше простого sequence of prompts?
Почему multi-agent conversation без termination condition опасна?
Как MCP связан с runtime framework, но не заменяет его?
Какие признаки говорят, что runtime framework уже оправдан?

Что дальше

Следующие модули показывают, как автоматизировать safety layer: hooks, guardrails, observability и evals. Runtime без этих слоев трудно сделать управляемым.