From 15483fc7d3abb8b03ee62757befb1b8978b2663b Mon Sep 17 00:00:00 2001 From: Ruben Koster Date: Mon, 10 Aug 2026 16:49:20 +0200 Subject: [PATCH] Add research note: OpenAI Agents SDK --- research/openai-agents-sdk.md | 135 ++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 research/openai-agents-sdk.md diff --git a/research/openai-agents-sdk.md b/research/openai-agents-sdk.md new file mode 100644 index 0000000..b035ce2 --- /dev/null +++ b/research/openai-agents-sdk.md @@ -0,0 +1,135 @@ +--- +title: "OpenAI Agents SDK — Minimal Primitives, Provider-Agnostic Agent Loop" +author: Ruben Koster (@rkoster) +date: 2026-08-10 +tags: [orchestration, inter-agent-comms, observability-governance, ecosystem-survey] +cf_areas: [] +status: draft +sources: + - https://github.com/openai/openai-agents-python + - https://openai.github.io/openai-agents-python/ + - https://openai.github.io/openai-agents-python/agents/ + - https://openai.github.io/openai-agents-python/tools/ + - https://openai.github.io/openai-agents-python/guardrails/ + - https://openai.github.io/openai-agents-python/handoffs/ + - https://openai.github.io/openai-agents-python/multi_agent/ + - https://openai.github.io/openai-agents-python/sessions/ + - https://openai.github.io/openai-agents-python/mcp/ + - https://openai.github.io/openai-agents-python/tracing/ + - https://openai.github.io/openai-agents-python/models/ + - https://github.com/openai/openai-agents-js + - https://github.com/openai/swarm +--- + +## Summary + +The OpenAI Agents SDK (`openai-agents-python`, MIT-licensed) is a lightweight, +provider-agnostic Python framework for building multi-agent workflows — explicitly a +"production-ready upgrade" of OpenAI's earlier experimental **Swarm** project. Its +architecture centers on a small primitive set: `Agent` (LLM + instructions + tools + +guardrails + handoffs), `Runner` (executes the agent loop), `handoffs` and `agents-as-tools` +(two complementary multi-agent orchestration patterns), and `guardrails` (input/output +validation). It ships built-in `Sessions` for conversation-history persistence (SQLite by +default, with pluggable Redis/SQLAlchemy/MongoDB/Dapr/encrypted backends) and built-in +`Tracing` integrated with OpenAI's hosted dashboard, plus an extensive third-party +observability ecosystem. It has no built-in durable-execution engine of its own — that gap is +explicitly filled by separate integrations from Temporal and Dapr Agents (both covered +elsewhere in this research set). + +## Key findings + +- **Origin, license, governance, Swarm lineage**: MIT-licensed, maintained directly under the + `openai` GitHub org. Docs explicitly state it is "a production-ready upgrade of our previous + experimentation for agents, Swarm" — Swarm remains available but is framed as an + educational/experimental predecessor, superseded by this SDK. A first-party JS/TS sibling + (`openai-agents-js`) also exists. +- **Adoption signal**: ~28.5k GitHub stars, ~4.5k forks, 2,040+ commits on `main` — a large, + active repo with a dedicated TypeScript sibling, indicating broad usage beyond OpenAI's own + docs/examples. +- **Deliberately minimal core primitives**: `Agent` (LLM + instructions + tools + guardrails + + handoffs), `Runner` (runs the agent loop via `run`/`run_sync`/`run_streamed`), `RunConfig` + for per-run overrides, and `Sessions` for memory — stated design principles are "enough + features to be worth using, but few enough primitives to make it quick to learn" and "works + great out of the box, but customizable." +- **Two named, complementary multi-agent patterns**: **handoffs** transfer full control of the + conversation to a specialist agent, which becomes the active agent for the rest of the turn + (best when a specialist should own user interaction directly). **Agents-as-tools** + (`Agent.as_tool()`) keep a manager agent in control, calling specialist agents as callable + tools and synthesizing outputs (best when a manager must own the final answer or combine + multiple specialists' outputs under one guardrail surface). The two can be combined — a + handoff target can itself call other agents as tools for narrow subtasks. +- **Tools span function tools, hosted tools, and MCP**: any Python function becomes a tool via + automatic schema generation; hosted tools (web search, file search, code interpreter, + computer use) run inside OpenAI's Responses API infrastructure; MCP servers are supported + via four transports — hosted `HostedMCPTool` (server-side), `MCPServerStreamableHttp`, + deprecated `MCPServerSse`, and local-process `MCPServerStdio` — with tool filtering, prompt + retrieval, caching, and approval-policy gating for sensitive MCP tool calls. +- **Sessions provide client-managed conversation memory, not a durable-execution substrate**: + `Session` objects (`SQLiteSession` default; extensions for `RedisSession`, + `SQLAlchemySession`, `MongoDBSession`, `DaprSession`, `OpenAIConversationsSession`, + `EncryptedSession`) automatically retrieve/persist history around a run. Interrupted/paused + runs (e.g. pending human approval) can be resumed via `result.to_state()` → + `state.approve(...)` → re-run against the same session — turn-level resumption, not + workflow-engine-style replay/crash recovery. +- **A first-party-documented `DaprSession`**: the SDK docs list `DaprSession` (via Dapr + state-store sidecars, 30+ backends, TTL/consistency controls) as a built-in session + implementation, confirming the Dapr↔OpenAI-Agents-SDK integration referenced in + `dapr-agents.md` is real and maintained — though it addresses session/memory storage + specifically, not full agent-execution durability. +- **Built-in tracing, no native OTel export**: tracing is enabled by default, capturing + `agent_span`, `generation_span`, `function_span`, `guardrail_span`, `handoff_span`, viewable + in OpenAI's hosted Traces dashboard. 25+ third-party "ecosystem integrations" (Datadog, + Langfuse, MLflow, Arize-Phoenix, W&B Weave, etc.) consume the tracing API surface via each + vendor's own instrumentation — not a standardized OTel exporter shipped by OpenAI itself, + unlike Google ADK's native OTel GenAI convention support (`google-adk.md`, + `opentelemetry-genai.md`). Tracing is unavailable for orgs under Zero Data Retention. +- **No native A2A protocol support found**: neither the README, docs navigation, nor the + multi-agent/MCP pages reference the Agent2Agent protocol; multi-agent coordination is scoped + to in-process handoffs/agents-as-tools (plus an experimental OpenAI-hosted multi-agent beta) + rather than a standardized cross-process wire protocol like A2A — contrast with Google ADK's + first-party bidirectional A2A support (`google-adk.md`). +- **No durable-execution engine; "bring your own infrastructure" deployment**: the SDK is a + library, not a hosted runtime/platform (unlike LangGraph Platform or Vertex Agent Engine) — + no bundled server, scheduler, or workflow-replay engine. This is consistent with why + dedicated durable-execution integrations exist as separate projects: Temporal's and Dapr + Agents' official integrations with this SDK exist precisely to backfill this gap + (`temporal.md`, `dapr-agents.md`). +- **Low provider lock-in by design**: default models are OpenAI's, on either the Responses API + (recommended) or Chat Completions API, but the SDK advertises "100+ other LLMs" support + through a custom `ModelProvider` per run, per-agent model overrides (mixing + providers/models within one workflow), and two first-party third-party adapters — Any-LLM + and LiteLLM — plus a `MultiProvider` for prefix-based model routing. +- **Guardrails and HITL are first-class, run-parallel constructs**: input/output guardrails + run in parallel with agent execution and can fail fast before wasting further LLM calls; a + dedicated human-in-the-loop mechanism supports interruption/approval flows with resumable + run state. An experimental "hosted multi-agent" mode lets a root agent create and coordinate + server-hosted subagents while local function tools still execute client-side — explicitly + incompatible with SDK handoffs. + +## CF relevance + +The OpenAI Agents SDK's minimal-primitives philosophy (a handful of composable concepts vs. a +full graph engine) is a useful contrast point to the heavier frameworks in this survey +(LangGraph, Microsoft Agent Framework, Google ADK) — it demonstrates that a lightweight, +library-only agent SDK with no bundled hosting/durability layer is a viable, widely-adopted +design point, not just a stepping stone toward a full platform. Its complete reliance on +external durable-execution integrations (Temporal, Dapr Agents) rather than shipping its own +is a clean illustration of the "agent framework vs. durability substrate" separation of +concerns CF should expect to make explicit in its own agent runtime story. The `DaprSession` +integration is also a concrete existing bridge CF could point to if evaluating Dapr as a +session/state substrate independent of which agent framework produced the workload. + +## Open questions + +- Given the SDK ships no hosting/runtime layer at all, would a CF-native "agent buildpack" + for this SDK look meaningfully different from a generic Python buildpack — i.e. is there + anything platform-specific to add, or does it just need process supervision plus a bound + session-store service? +- Is the SDK's reliance on external durability integrations (Temporal, Dapr) a pattern CF + should standardize on — i.e. should CF's own agent runtime treat "durable execution" as a + pluggable, bindable capability rather than a framework-level feature? +- How significant is the lack of native A2A support for CF's cross-framework interoperability + goals, given this is one of the most widely-adopted agent SDKs surveyed? +- The experimental "hosted multi-agent" mode moves orchestration server-side into OpenAI's own + infrastructure — does this signal a broader industry shift toward vendor-hosted + orchestration that CF should watch for parallels to Vertex Agent Engine or Azure Foundry?