OpenAI Agents SDK чи LangGraph: як обрати оркестрацію агентів

OpenAI Agents SDK доцільний, коли потрібен компактний model-led agent loop із tools, agents-as-tools або handoffs, guardrails, sessions і вбудованим tracing. LangGraph доцільний, коли команда хоче явно моделювати довгий stateful workflow як граф, зберігати checkpoints, переривати виконання, відновлювати його після збою та контролювати кожен перехід. Це не рейтинг якості моделей: обидва підходи можуть викликати LLM та зовнішні інструменти, але розміщують orchestration complexity у різних місцях.

Починайте не з framework, а з task contract: terminal outcome, максимальна тривалість, owner стану, дозволені side effects, approval points, recovery objective і потрібна переносимість між провайдерами. Якщо задача завершується за один bounded run і природно виражається через delegation, простіші primitives SDK зменшують обсяг власного orchestration code. Якщо процес живе довше за один запит, має цикли, очікує людину або повинен відновитися з конкретного кроку, явний durable graph дає кращу операційну модель. Для простого tool-calling assistant не потрібен жоден складний multi-agent workflow.

OpenAI Agents SDK — набір невеликої кількості agent primitives для Python і TypeScript: agent, runner, function tools, handoffs, agents as tools, guardrails, sessions та tracing. Runner керує циклом model call → tool call → observation → наступний turn до фінального результату або ліміту. LangGraph позиціонується як низькорівневий orchestration runtime для long-running stateful agents: вузли читають і оновлюють typed state, ребра визначають control flow, а checkpointer зберігає snapshots за кроками.

Порівнювати слід runtime abstractions, а не весь vendor stack. LangGraph можна використовувати без LangChain, а LangSmith є окремим сервісом для observability та evaluation. Agents SDK може працювати з іншими model providers через adapter interfaces, але його найкоротший шлях інтегрований з OpenAI. Аналогічно, наявність tracing у SDK не означає автоматичної відповідності вашій privacy policy, а checkpointing у LangGraph не робить бізнес-операції транзакційними. Hosting, identity, secrets, domain database, queues і incident response залишаються архітектурними рішеннями застосунку.

Для conversation agent із кількома tools, короткою тривалістю і model-led routing Agents SDK дає прямий baseline. Handoff передає активну розмову спеціалісту, тоді як agent-as-tool дозволяє manager зберегти контроль і отримати структурований результат підзадачі. Guardrails можна розмістити на input, output та custom function tools. Sessions допомагають підтримувати conversation context, але domain state — статус замовлення, approval або платіж — не повинен існувати лише в session history.

Для процесу на години або дні, явних parallel branches, human approval між кроками, replay чи resume після crash LangGraph має природнішу модель. Persistence зберігає state checkpoints у threads; interrupts дозволяють призупинити граф і продовжити його з durable state. Плата за контроль — більше явної схеми: reducers, node contracts, transition tests, checkpoint migration і правила повторного виконання. Граф корисний лише тоді, коли ці стани справді є частиною продуктового процесу, а не візуальним оформленням простого циклу.

Гібрид можливий: bounded Agents SDK runner може бути одним вузлом ширшого durable workflow, або deterministic application workflow може викликати agent лише для класифікації чи synthesis. Водночас вкладення одного orchestration runtime в інший створює дві моделі retries, traces і state ownership. Використовуйте його лише з чіткою межею: зовнішній runtime володіє lifecycle та checkpoints, внутрішній agent run не виконує неперевірені irreversible side effects і повертає typed result.

• Короткий model-led loop, tools і delegation → спершу перевірте Agents SDK.
• Довгий workflow, explicit branches, checkpoints і resume → спершу перевірте LangGraph.
• Один передбачуваний process без adaptive routing → звичайний application workflow може бути кращим за обидва.
• Provider portability → протестуйте adapters, tool schemas, tracing і model-specific behavior, а не довіряйте абстрактній обіцянці.
• Hybrid → один runtime має бути остаточним власником state, retry та terminal outcome.

Conversation memory відповідає на питання, який контекст потрібен наступному model turn. Workflow state відповідає, який крок виконано, що очікується і які інваріанти діють. Durable execution додає відновлення після process або infrastructure failure. У Agents SDK sessions керують history між runs; для довгих або durable сценаріїв потрібно окремо визначити persistent job state чи інтеграцію з workflow system. У LangGraph checkpointer фіксує channel values, next nodes і metadata, що підтримує resume, human-in-the-loop та time-travel debugging.

Checkpoint не гарантує exactly-once side effect. Якщо node виконав refund, але впав до надійного запису результату, resume може повторити дію. У будь-якому framework mutating tool потребує idempotency key, authoritative postcondition, bounded retry та reconciliation. State schema версіонується; великі documents і secrets зберігаються у відповідних системах, а graph/session містить references. Retention, deletion, tenant isolation та encryption планують до запису першого production checkpoint або trace.

Handoff у Agents SDK змінює активного агента в межах run; документація окремо наголошує, що input guardrails застосовуються до першого агента, output guardrails — до агента фінальної відповіді, а для кожного custom tool потрібні tool guardrails. Handoff history також слід фільтрувати, щоб specialist не отримав зайві персональні дані або недовірені tool outputs. У LangGraph edge або conditional routing визначає наступний node, але сам перехід не видає identity чи permission.

Застосунок формує policy envelope незалежно від runtime: authenticated actor, tenant, resource, action, risk tier, scopes, expiry і approval state. Tool перевіряє envelope безпосередньо перед виконанням. Модель може запропонувати handoff або route, проте не може розширити scopes. High-impact transition зупиняється перед side effect, показує людині конкретний diff і після approval повторно перевіряє актуальність ресурсу. Audit пов’язує model decision, runtime transition, policy verdict, tool attempt і verified outcome одним correlation ID.

Agents SDK має built-in tracing для generations, tool calls, handoffs, guardrails і custom spans. За офіційною документацією tracing увімкнено за замовчуванням, його можна вимкнути або не включати sensitive data; він недоступний для організацій із Zero Data Retention policy. Це важлива design constraint: перед rollout перевірте, куди надходять traces, які поля редагуються та який fallback telemetry потрібен. LangGraph надає state/history primitives, а глибоке trace UI зазвичай пов’язують із LangSmith або власним OpenTelemetry pipeline.

Порівнюйте не красу dashboard, а forensic completeness. Для кожного run потрібні task ID, runtime і version, model, state/checkpoint version, node або active agent, tool inputs fingerprint, policy result, latency, usage, terminal reason і verified business outcome. Сирі prompts не повинні автоматично ставати довгостроковим логом. Alerts прив’язують до stuck runs, repeated side effects, unauthorized attempts, checkpoint failures і деградації task success, а не лише до HTTP error rate.

Візьміть 30–50 репрезентативних задач із простими, складними та ризиковими slices; це розмір engineering corpus, а не статистична обіцянка. Реалізуйте однаковий task contract: ті самі tools, policy service, model where practical, terminal schema і evaluation rubric. Один prototype використовує найпростіший придатний Agents SDK pattern, другий — мінімальний LangGraph. Не оптимізуйте лише улюблений варіант і не додавайте feature, якої немає в production requirement.

Вимірюйте task success, schema validity, tool-call accuracy, prohibited-action rate, recovery success після injected failure, reviewer effort, p95 time-to-verified-outcome і cost per accepted outcome. Окремо перевірте crash після side effect, process restart, expired approval, changed permissions, malformed tool result, prompt injection, checkpoint incompatibility та trace redaction. Рішення фіксує не лише переможця, а й причину: наприклад, explicit resume після approval переважує додатковий graph code, або короткі runs не виправдовують складність checkpoint lifecycle.

Rollout іде від offline replay до shadow, read-only canary та bounded writes. Framework приховується за внутрішніми TaskRunner, ToolContract і RunEvent interfaces настільки, наскільки це підтверджує реальна потреба заміни; не створюйте універсальний adapter наперед. Rollback зупиняє нові runs, ізолює in-flight state, звіряє side effects і повертає попередній runner. Активні checkpoints мігрують лише за протестованою схемою або завершуються старою версією.

• Зафіксувати task, authority, state і recovery contracts до prototype.
• Побудувати мінімально чесні реалізації на однакових inputs і tools.
• Інжектувати failure після tool commit і до state persistence.
• Оцінити critical slices, privacy та operator burden разом із quality і cost.
• Зберегти feature flag, reconciliation runbook і сумісний rollback path.

Станом на перевірку first-party документації обидва runtime підтримують human-in-the-loop, але їхні pause/resume contracts треба тестувати окремо. OpenAI Agents SDK серіалізує перерваний run у RunState, показує approval items і продовжує виконання після approve або reject; документація також описує збереження такого стану в session та окремі long-running approval flows. LangGraph interrupt зберігає graph state через checkpointer, повертає JSON-serializable payload caller-у й очікує повторного invoke з Command. Однакова кнопка «Approve» не означає однаковий lifecycle, retention або recovery behavior.

Перед вибором визначте pause envelope: stable run/thread ID, schema version, requested action, normalized arguments, resource version, requester, approver policy, expiry, resume token, allowed decision set і destination після відновлення. Approval не має бути дозволом «продовжити все». Після resume tool повторно перевіряє actor, scopes, current resource version і postcondition; expired або materially changed request повертається на review. Серіалізований model context не є authorization record, а session чи checkpoint не замінює domain audit ledger.

Failure drill повинен покрити restart до approval, restart після approval але до side effect, commit side effect до checkpoint, duplicate resume, reject, timeout і schema upgrade. Для LangGraph врахуйте задокументовану семантику: node починається спочатку під час resume, тому side effects перед interrupt мають бути idempotent. Для Agents SDK перевірте, де саме зберігається RunState, як він шифрується, хто може відновити run і чи переживає deployment ваш session backend. Verdict формується за verified terminal outcome, а не лише за успішним resume API.

• Pause receipt → runtime/version, run or thread ID, state schema, pending action і checkpoint/session reference.
• Approval receipt → approver, decision, exact argument hash, expiry та policy version.
• Resume receipt → reauthorization result, replay count, tool attempt і verified postcondition.
• Recovery verdict → completed, rejected, expired, reconciled або manually quarantined.

Framework portability оцінюйте через executable packet. Збережіть task fixtures, typed terminal schema, tool contracts, policy decisions, model settings, prompt assets, state schema, checkpoint/session fixtures, trace vocabulary та acceptance rubric. Потім складіть semantic map: Agents SDK agent, handoff, agent-as-tool, session, RunState і trace span не мають автоматичної взаємно однозначної відповідності LangGraph node, edge, subgraph, checkpointer, interrupt і state history. Позначайте кожне відображення як equivalent, adapted, dropped або runtime-specific.

Найнебезпечніша міграція — механічно перенести persistence. Conversation history, workflow checkpoint, cross-thread memory і authoritative business record мають різних owners та retention rules. Export містить лише мінімальні references і versioned state, ніколи не покладається на opaque serialized object як довічний контракт. Новий runtime спочатку імпортує sanitized fixtures у staging, replay-ить їх без writes і доводить terminal-schema parity, approval parity, trace correlation та rollback. In-flight production runs або завершуються старою версією, або проходять окремий tested migrator; їх не підхоплюють новим runner за припущенням.

Exit criteria вимірюють переносимість за роботою, яку справді доведеться повторити: частка tool schemas без змін, кількість runtime-specific state fields, replay verdicts, ручні migration steps і unresolved authority differences. Це engineering evidence для вашого corpus, а не універсальний рейтинг framework. Якщо replacement не є реальною вимогою, тонкий application-owned boundary навколо TaskRequest, ToolContract, ApprovalDecision і TerminalResult корисніший за універсальну orchestration abstraction, яка приховує recovery semantics.

• Portable → task fixtures, domain schemas, policy inputs, tool postconditions і acceptance rubric.
• Adapted → routing, pause/resume, retry, trace та state-transition semantics.
• Runtime-specific → serialized execution state, internal span types і deployment controls.
• Rollback → stop new starts, preserve old runner for in-flight state, reconcile writes, restore routing flag.