OpenAI Agents SDK чи Claude Agent SDK: практичний вибір

OpenAI Agents SDK варто прототипувати першим, коли потрібен компактний application-level loop із agents, tools, handoffs або agents-as-tools, guardrails, sessions, approval interruptions і вбудованим tracing. Claude Agent SDK варто прототипувати першим, коли продукту підходить Claude Code agent harness як бібліотека: вбудовані file/shell/web capabilities, MCP, permission modes, allow/deny rules, lifecycle hooks, subagents і sessions із continue, resume або fork. Це різні операційні форми, а не таблиця «яка модель розумніша».

Якщо процес здебільшого deterministic, обидва SDK можуть бути зайвими: workflow engine має володіти чергою, retries і бізнес-станом, а модель отримує вузький typed task. Якщо потрібен відкритий multi-provider baseline, перевірте його окремо: OpenAI SDK документує підтримку інших model providers, тоді як Claude Agent SDK є harness навколо Claude Code і Claude. Заявлена сумісність усе одно не гарантує однакових tool semantics, structured output, usage accounting чи traces.

OpenAI Agents SDK дає primitives для Agent, Runner, function і hosted tools, handoffs, agents-as-tools, guardrails, sessions, RunState та traces. Runner веде model → tool → observation цикл до terminal output, interruption або ліміту. Це зручний шар для застосунку, який сам володіє identity, policy, domain services і deployment, але хоче стандартизувати agent loop та його evidence.

Claude Agent SDK експонує той самий agent harness, що живить Claude Code: Claude сам досліджує контекст, викликає built-in або MCP tools і може працювати через subagents. SDK має Python і TypeScript surfaces, але capability треба перевіряти у потрібній версії. Сильна сторона — готове середовище для repository, filesystem і computer-like tasks; ці ж можливості збільшують blast radius, якщо permission boundary спроєктована після prototype.

• Керований application agent із власними typed tools і delegation → OpenAI SDK як перший baseline.
• Claude Code-style agent із filesystem/shell, MCP, hooks і subagents → Claude SDK як перший baseline.
• Deterministic business process → звичайний orchestrator із вузьким model step.
• Provider portability → реальний replay на кожній adapter/model pair, а не висновок із логотипів.

У OpenAI SDK tool approval може перервати run, повернути serializable state і продовжити виконання після рішення. Guardrails перевіряють input, output або tool path у визначених точках. У Claude SDK permission modes, declarative allow/deny rules і callback canUseTool керують доступом до tools; hooks можуть перехоплювати події до та після tool call. Обидва механізми корисні, але framework policy не знає, хто має право повернути кошти, змінити production або прочитати запис конкретного tenant.

Application policy повинна перевіряти authenticated actor, tenant, resource, action, credential owner, risk tier і поточний стан. Approval прив'язується до exact payload hash, tool/version і expiry. Після pause/resume identity, scope та precondition перевіряються знову. Не використовуйте bypass-permissions або blanket allowlist як production shortcut: модель не може розширити власні права, а hook failure має fail closed для consequential action.

OpenAI sessions зберігають conversation history, а RunState представляє перерване виконання, зокрема approval flow. Claude sessions зберігають conversation history і дозволяють continue останню сесію, resume за ID або fork у нову гілку. Це контекст виконання, а не system of record. Order status, payment approval, entitlement або deployed revision не можна зберігати лише в transcript чи serialized run.

Resume особливо небезпечний біля side effect. Якщо tool створив ресурс, але process упав до запису наступної події, повтор може створити дубль. Потрібні idempotency key, read-after-write reconciliation, bounded retry і terminal state незалежно від SDK. Версіонуйте prompt/agent config, tool schema, permission policy, session format і model route; incompatible session переходить у migration або review lane.

OpenAI handoff передає контроль іншому agent, тоді як agent-as-tool залишає manager власником фінального synthesis. Claude subagents отримують окремий context window, prompt і tool scope та повертають результат головному agent. В обох випадках topology повинна відповідати реальній незалежності задачі. Один agent із трьома tools часто надійніший за команду персонажів, які дублюють контекст і приховують responsibility.

Для кожного delegation event записуйте parent run, child agent/version, input contract, granted tools, budget, terminal reason і evidence returned. Subagent не успадковує всі credentials лише тому, що parent може його викликати. Parallel work потребує лімітів, conflict policy і merge owner; два агенти не повинні одночасно вважати себе остаточним власником того самого side effect.

Claude hooks дають lifecycle interception для policy, logging, validation і transformation навколо agent events. OpenAI SDK має guardrails і built-in tracing для generations, tools, handoffs та custom spans. Ці surfaces не є взаємозамінними, але повинні проєктуватися у спільний внутрішній RunEvent: task ID, SDK/version, model, agent, tool fingerprint, permission decision, latency, usage, interruption, terminal reason і verified outcome.

Не відправляйте raw prompts, secrets і повні tool outputs у telemetry за замовчуванням. До pilot перевірте redaction, retention, tenant isolation, trace export, sampling і поведінку при outage. Hook або tracing backend не повинен ставати непомітним власником execution availability; критична policy перевірка fail-closed, а необов'язкова telemetry деградує без розширення authority.

Зберіть 30–50 репрезентативних engineering cases як corpus для рішення, а не як статистичну обіцянку. Реалізуйте однакові TaskContract, ToolContract, PolicyDecision, TerminalResult і RunEvent навколо мінімального prototype кожного SDK. Для repository agent дайте pinned snapshot, isolated worktree, однакові checks і branch-only write; для business agent — ті самі sandbox services та permission fixtures.

Інжектуйте malformed tool result, prompt injection у файлі або MCP response, permission revocation, timeout до й після side effect, session corruption, rate limit, restart, telemetry outage і conflicting parallel writes. Порівнюйте verified task success, prohibited-action rate, recovery, schema validity, reviewer minutes, latency і full cost per accepted outcome. Не використовуйте vendor benchmark як заміну власному critical slice.

Exit drill завершує proof: зупиніть нові runs, відновіть in-flight work, reconcile side effects і перенесіть один task через власні contracts або назад у deterministic workflow. Framework-specific orchestration може залишатися видимою; identity, domain state, policy, tool schemas та audit envelope мають належати застосунку.

• До prototype → task, authority, state, telemetry та terminal contracts.
• Під час prototype → однакові fixtures, failures і acceptance checks.
• Перед pilot → redaction, kill switch, resume/reconcile та session migration drill.
• Перед write access → payload-bound approval й idempotent side effects.
• Перед scale → operator load, cost per verified outcome і перевірений exit path.

Обирайте OpenAI Agents SDK, якщо ваш reference task природно описується agents, typed tools, handoffs/agents-as-tools, sessions, approval interruption і trace surface, а deployment та policy вже належать application platform. Обирайте Claude Agent SDK, якщо reference task виграє від Claude Code harness, built-in computer-like tools, MCP, permission modes, hooks, subagents і session resume/fork. Обирайте neither, якщо більшість кроків відома наперед і agent loop лише маскує звичайний workflow.

Фінальне рішення має бути versioned ADR із task scope, дозволеними tools, state owner, evaluation results, failure evidence, cost boundary, rollback і review date. SDK оновлюється; тому capability matrix є snapshot на 2026-08-24, а не довічним рейтингом. Повторюйте critical replay перед model, SDK, permission або session-schema upgrade.

Назва SDK не визначає, де реально виконується небезпечний tool. OpenAI Agents SDK розділяє hosted tools, hosted container shell і local/runtime tools: ComputerTool та ApplyPatchTool потребують реалізації у вашому середовищі, а ShellTool може працювати локально або в OpenAI-hosted container. Claude Agent SDK підтримує sandbox configuration, але production hosting guide рекомендує запускати SDK worker усередині sandboxed container; conversational state і команди живуть у persistent execution environment, який команда повинна ізолювати та обслуговувати. Порівнюйте конкретний deployment profile, а не абстрактні SDK defaults.

Створіть ExecutionProfile для кожного prototype: image digest, writable roots, read-only mounts, process user, CPU/memory/time limits, network default, allowlisted destinations, DNS policy, secret broker, artifact export, persistence window і teardown evidence. Для OpenAI hosted container перевірте network disabled або allowlist mode та відокремте domain-scoped secret injection від model-visible data. Для local OpenAI tools і Claude worker застосуйте власні OS/container controls; permission prompt або allow rule не замінює filesystem та egress isolation.

Найсильніший негативний тест поєднує prompt injection із доступним секретом і мережею. Покладіть canary token у недозволене місце, додайте malicious instruction у repository або MCP result і спробуйте прочитати token, передати його на неallowlisted host та записати поза workspace. Успішний захист означає, що OS/network boundary блокує дію незалежно від model compliance. Лог має фіксувати denial без значення секрету; після run ephemeral worker знищується, а persistent volume проходить окрему retention policy.

• Hosted execution → зафіксуйте provider boundary, network policy, persistence і artifact export.
• Local execution → ізолюйте process, workspace, credentials і egress у власній інфраструктурі.
• Persistent session → не перетворюйте execution filesystem на неявний system of record.
• Secret access → short-lived brokered credential, вузька audience і жодного raw secret у prompt або trace.
• Teardown → revoke lease, terminate worker, reconcile side effects і зберегти лише дозволаний evidence.

У OpenAI SDK function-tool guardrails можуть перевіряти input і output, але офіційна документація прямо обмежує цей pipeline: він не охоплює handoff, hosted tools, ComputerTool, ShellTool, ApplyPatchTool, LocalShellTool або Agent.as_tool. У Claude SDK порядок перевірки включає hooks, deny rules, permission mode, allow rules і canUseTool; deny rule зберігає пріоритет навіть для bypassPermissions, але це все одно framework layer. Тому твердження «ми ввімкнули guardrails» або «ми маємо deny list» нічого не доводить без карти всіх execution paths.

Побудуйте PolicyCoverageMap із рядками для function, hosted search, MCP, shell, computer, patch, handoff/subagent і domain API. Для кожного вкажіть model-visible schema, pre-execution enforcement point, approval behavior, OS/network boundary, credential source, output validation, audit event і failure mode. Непокритий рядок не переходить у write-enabled pilot. Якщо SDK primitive не перехоплює конкретний tool type, контроль переноситься у tool adapter, sandbox, proxy або domain service, а не компенсується prompt instruction.

Перевірте map автоматизованими contract tests: exact payload змінюється після approval; allowlisted shell command додає pipe або redirect; MCP catalog підмінює schema; handoff отримує ширший tool set; hosted tool повертає інструкцію для exfiltration; policy service недоступний. Очікувані результати — deny, нове approval або bounded read-only degradation. Після upgrade повторіть тести на pinned SDK version, бо новий tool type чи інший execution route може створити непомітну прогалину в coverage.

• Inventory → усі tool, delegation і hosted execution paths без узагальнення словом guardrail.
• Enforcement → точний компонент, який може зупинити дію до side effect.
• Approval → payload hash, actor, expiry і повторна policy перевірка після resume.
• Failure → fail closed для consequential action; telemetry outage не розширює authority.
• Upgrade gate → coverage diff і негативний replay перед зміною SDK або tool surface.