OpenAI Agents SDK + Responses API

1. Introduction

1.1. Platform Positioning and Origin

On 2025-03-11, OpenAI released a set of building blocks for agent development, which its official blog summarized as four items:

1. Responses API — a new API primitive that combines the simplicity of Chat Completions with the tool-use capabilities of the Assistants API;
2. Built-in tools — web search, file search, computer use;
3. Agents SDK — an open-source framework for multi-agent orchestration;
4. Built-in observability — tracing.

Officially, the stated motivation was: customers reported that "turning these capabilities into production-ready agents is hard, often requiring extensive prompt iteration and custom orchestration logic, and lacking visibility and built-in support." That statement is itself another definition of Harness — when orchestration and observability have to be rebuilt by each team, the industry needs a standardized hosting layer.

Compared with Anthropic's Claude Agent SDK, OpenAI's approach shows a clear difference in path: Anthropic first productized its internal tool (Claude Code) and then opened it up as an SDK, while OpenAI first defined API primitives and then layered a lightweight framework on top. The former emphasizes the execution surface (file system, Bash, sandbox), while the latter emphasizes the interface surface and model-side tools.

1.2. Basic Information Card

1.3. Development Timeline

1.4. Position in the AI Harness System

OpenAI officially decomposes agent systems into four composable parts: Models (reasoning engine), Tools (executable actions), State and memory (cross-step memory), Orchestration (coordination of multiple agents and tools). This maps to the six-layer model of the parameter card as follows:

Notably, OpenAI's four-way division does not separately list L5 (evaluation and observability) or L6 (governance and security). This is not an omission but a product division of labor — evaluation is provided by Evals on the OpenAI platform, observability by tracing, and governance by Guardrails. This form of "different layers being borne by different products" is precisely the structural difference between this platform and an integrated Harness.

2. Glossary

3. Feature Description

3.1. Positioning and Capabilities of the Responses API

The Responses API is officially positioned as "the default entry point for new integrations," and its core improvements include:

• Unified design: a unified item-based structure, replacing the multiple forms of the former message array;
• Simpler polymorphism: fewer type branches;
• More intuitive streaming events;
• SDK helpers: convenient access such as response.output_text;
• A single call can complete multiple tools across multiple turns: one API call can internally run several model turns.

OpenAI has explicitly stated that Chat Completions will continue to be supported long-term and keep receiving new models, but new features that do not depend on built-in tools or multi-model calls are only released on Chat Completions; new integrations are advised to start from the Responses API.

3.2. Three Categories of Built-in Tools

The three tools differ enormously in price and reliability, which must be explicitly considered in the L2 and L6 trade-offs: computer use is the tool with the highest capability ceiling and the lowest predictability.

3.3. Core Primitives of the Agents SDK

Officially, the SDK's design orientation is "deliberately lightweight": no graph topology is required, no proprietary abstractions are introduced, and readability and extensibility are emphasized. This forms a direct contrast with LangGraph's explicit-graph orientation.

3.4. Guardrails Mechanism

Guardrails are safety checks that run in parallel with the main response:

• Input guardrails: trigger before the main agent responds, suitable for topic classification, PII detection, and abuse screening;
• Output guardrails: trigger after the response, suitable for policy compliance, hallucination checks, and format validation;
• On trigger, GuardrailTripwireTriggered is thrown, interrupting the workflow.

Two engineering facts are worth noting:

1. Guardrails run in parallel but still add measurable latency, and output guardrails in particular must wait for the main response to finish before they can be evaluated;
2. If a guardrail itself calls a second model, each user interaction incurs an extra full inference round-trip.

3.5. Tracing Observability

Each run automatically generates a complete trace, covering: agent calls, tool calls, handoff decisions, guardrail evaluations, and token usage. By default it is sent to the OpenAI platform (viewable in the dashboard), and it can be exported to third-party observability tools.

This is the core advantage of this platform over "bare API calls": observability is built in, not bolted on.

But it should also be noted: by default the trace resides on the OpenAI side, which creates a tension with data-residency compliance (see 3.7).

3.6. Sessions and Memory

• Server-hosted: previous_response_id chains multiple turns; when store: true, history is stored within OpenAI infrastructure.
• Client-hosted: store: false plus maintaining the message history yourself, suitable for scenarios with data-governance requirements such as healthcare, legal, and finance.
• Session abstraction: the SDK provides a session layer responsible for saving and restoring cross-turn history.

3.7. Known Production Issues

The following issues come from summaries of public engineering practice and are risks that must be evaluated before adoption:

4. Platform Architecture

图 4-1｜OpenAI Agents SDK 五层架构：从应用层到模型层

数据来源：基于本文分析绘制的示意图。

4.1. Layered Architecture

┌──────────────────────────────────────────────────────────┐
│ 应用层：你的业务代码                                        │
│  Agent 定义（instructions / model / tools / output_type）  │
│  Handoff 关系、Guardrail 注册                              │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ OpenAI Agents SDK（开源）                                  │
│  Runner.run() 循环                                        │
│  ├─ Handoff Router（transfer_to_<agent> 普通函数调用）      │
│  ├─ Guardrail Runner（并行 input / output 校验 + tripwire） │
│  ├─ RunContext（类型化状态，依赖注入到工具签名）             │
│  ├─ Session（跨轮次历史保存与恢复）                         │
│  └─ Tracing（轨迹采集，默认上报平台，可导出第三方）          │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ Responses API（/v1/responses）                             │
│  item-based 统一结构 · 流式事件 · output_text helper        │
│  previous_response_id 串联 · store 开关                    │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 工具层                                                     │
│  Hosted（web search / file search / computer use / code     │
│  interpreter / image generation）· Function · Agents-as-    │
│  Tools · MCP                                               │
└──────────────────────────────────────────────────────────┘
                          │
┌──────────────────────────────────────────────────────────┐
│ 模型层：OpenAI 模型 / 任意 Chat Completions 风格 API /        │
│ LiteLLM 接入的 100+ 第三方模型                              │
└──────────────────────────────────────────────────────────┘

4.2. Execution Flow of a Single Runner.run

1. Load Session history (if any) and assemble the RunContext;
2. Input guardrails trigger in parallel; if a tripwire is hit, interrupt immediately;
3. Call the model (Responses API);
4. If a tool call is returned: execute the tool (hosted / function / agent-as-tool / MCP), feed the result back, and return to step 3;
5. If a handoff is returned: call transfer_to_<agent>, switch to the target agent within the same session thread, and return to step 3;
6. After a final output is produced, output guardrails trigger in parallel; hit a tripwire to interrupt;
7. Write the trace (tracing) and update the Session.

4.3. Relationship with Assistants API / Swarm

The Agents SDK itself is the official successor to the experimental orchestration project Swarm.

5. Harness Design

5.1. Overview of the Six-Layer Capabilities

5.2. L1 Context Engineering Layer

The distinguishing feature of this platform at L1 is hosting retrieval on the model side:

• file search takes on the RAG responsibilities (ingestion, query optimization, metadata filtering, reranking), so developers do not need to build their own vector store;
• previous_response_id turns context reuse into a single parameter pass;
• the store switch decides where the context lives.

The shortcomings are equally clear:

• There is no context compression (Compaction) primitive; long sessions can only be handled by truncation or summarization implemented yourself;
• There is no priority-ordering mechanism; the order and trimming strategy by which retrieval results enter the context are not controllable;
• Hosted context (store) directly conflicts with compliance requirements (see 3.7).

5.3. L2 Tools and Execution Layer

Four categories of tools form a complete capability surface:

The tension of openness ↔ governance is most visible at this layer: MCP and LiteLLM let agents reach any external system and any model, maximizing interoperability; but every integration is a new data exit and a new prompt-injection entry point. At the L2 side, this platform does not provide a "hook around tool calls" mechanism equivalent to Claude Agent SDK's Hooks; interception can only land on Guardrails (at the input / output level) — this is the key difference in governance granularity between the two.

5.4. L3 Orchestration and Control Layer

The L3 of this platform is lightweight implicit orchestration, which differs from both LangGraph's explicit graph and Claude Agent SDK's loop + subagent model:

• Control flow is expressed through handoffs, which are implemented as ordinary function calls and are therefore fully transparent in the trace;
• No predefined topology is required; delegation can be decided dynamically at runtime;
• There are only two interruption mechanisms: max_turns and the guardrail tripwire.

The concrete form of the flexibility ↔ predictability tension here is the handoff loop: because the SDK does not enforce a handoff depth limit by default, an A→B→A circular delegation does not error but instead manifests as a "hung run." This is the point at the L3 of this platform that most needs engineering defenses.

Comparison with similar solutions:

5.5. L4 Memory and State Layer

• Short-term: the Session abstraction is responsible for saving and restoring cross-turn history; on the platform side it is hosted by previous_response_id.
• Long-term: the SDK itself does not provide semantic long-term memory, episodic memory, or artifact checkpoints; an external vector store (Pinecone / others) or self-build is needed.
• Across runs: RunContext is valid only within a single Runner.run(); it does not span processes or survive restarts.

Conclusion: at this platform, L4 is a layer that is "adequate but not engineered" — compared with Claude Agent SDK's JSONL session persistence + resume/fork, its recovery and forking capabilities are weaker.

5.6. L5 Evaluation and Observability Layer

This is the plus factor of this platform relative to comparable SDKs:

• tracing is built in, and every run automatically produces structured traces;
• the traces cover agent calls, tool calls, handoff decisions, guardrail evaluations, and token usage;
• by default they are reported to the OpenAI dashboard, and can be exported to third parties.

But strictly speaking, tracing belongs to observability rather than evaluation:

• Golden Datasets, regression sets, and A/B testing must rely on OpenAI platform Evals or be self-built;
• There is no native "run the regression set on every submission" workflow.

Hence the judgment "medium–strong" — observability is strong, but evaluation must be bolted on.

5.7. L6 Governance and Security Layer

Compared with Claude Agent SDK, this platform lacks an amount-level budget guardrail (the equivalent of max_budget_usd). On the "cost ↔ depth" tension, the only controllable levers on this platform are max_turns and model-tier selection, so the cost ceiling is indirect.

5.8. Manifestations of Three Inherent Tensions

6. Use Cases

The following four cases all come from OpenAI's official blog of 2025-03-11; they are officially published customer cases, with no data extrapolation.

Case 1: Hebbia × Web Search

Hebbia serves asset managers, private equity and credit institutions, and law firms, needing to rapidly extract actionable insights from vast public and private datasets. After integrating the web search of the Responses API, it embedded real-time retrieval into its existing search workflow to provide contextually relevant market intelligence. The official statement credits improved accuracy and relevance of analysis, but no specific quantitative metrics were published.

Case 2: Navan × File Search

Navan is an AI-driven travel agency that uses file search to quickly give accurate answers drawn from knowledge-base articles (such as company travel policies). Its key engineering wins are: built-in query optimization and reranking mean a usable RAG pipeline can be assembled without additional tuning; per-user-group independent vector stores let answers be customized by account settings and user role. The official publication disclosed no quantitative metrics.

Case 3: Unify × Computer Use

Unify is an agent system aimed at revenue expansion, using computer use to reach information previously inaccessible via APIs. As an official example: in a real-estate management company scenario, an agent can confirm on an online map whether a company has expanded its office space, serving as a custom signal for outreach.

Case 4: Luminai × Computer Use

Luminai serves large enterprises that lack APIs and standardized data, automating complex business workflows. OpenAI disclosed that in a recent pilot with a large community-service organization, Luminai automated the application-processing and user-registration workflows in a matter of days, whereas traditional RPA approaches had failed to do so over several months. This is the only one of the four cases with a quantified time statement (source: OpenAI's official blog relaying a customer pilot).

Portions with no publicly retrieved quantitative data: none of the above cases published metrics such as cost-reduction percentages, task success rates, or human-replacement rates; as of the retrieval date 2026-09-12, no finer-grained third-party audit data was found, and this is noted truthfully here.

7. Summary

7.1. Advantages

1. Standardized interface surface: the Responses API merges the capabilities of Chat Completions and the Assistants API, reducing ecosystem fragmentation.
2. Mature model-side tools: web search (SimpleQA 90%) and file search are accurate and work out of the box, saving the need to build a RAG pipeline.
3. Built-in observability: tracing is automatically produced on every run and can be exported to third parties; the bar for observability is significantly lower than comparable offerings.
4. Lightweight and easy to start: no graph topology, no proprietary abstractions; just three concepts — Agent / Handoff / Guardrail — are enough to assemble a multi-agent system.
5. Swappable models: supports any Chat Completions-style API, can connect 100+ models via LiteLLM, so lock-in risk is low.

7.2. Disadvantages

1. L1 lacks compression and ordering primitives: long-session management must be implemented yourself.
2. L3 lacks graph semantics: handoff loops have no default depth limit; they manifest as hangs rather than errors.
3. No amount-level hard cost stop: there is only max_turns, with no budget-cap parameter.
4. No native approval queue or RBAC: human-in-the-loop collaboration for high-risk operations must be self-built.
5. Computer use has low reliability: OSWorld 38.1%, and OpenAI explicitly notes it is still affected by unexpected errors.
6. Data residency must be handled proactively: store: true puts history on the OpenAI side by default, so compliance scenarios must change the configuration.

7.3. Applicability Boundaries

7.4. Selection Recommendations

• If a team already uses the OpenAI platform deeply and its primary need is to quickly get a multi-agent system running, this platform is one of the lowest-cost options to get started.
• If the primary need is fine-grained interception and approval of tool calls, Claude Agent SDK's Hooks and canUseTool are more complete (see 01-claude-agent-sdk.md).
• If the primary need is regression-testable, assertable execution order, an explicit-graph framework should be chosen (see 04-langgraph.md).
• Three configurations must be completed before adoption: max_turns, a handoff fallback branch, and store: false + self-built history.

Information Gap Statement

1. Exact license: the open-source license type of the Agents SDK has not been checked against the repository's LICENSE file; marked [To be verified].
2. Current latest version number: only seen in third-party sources as "in the 0.6 series as of 2026-01," not officially confirmed; marked [To be verified].
3. Assistants API sunset timing: the official blog (mid-2026) and the official Help Center (removal in August 2026) differ; both wordings are listed without unification.
4. Session's persistence backend: public materials mention the Session abstraction but do not provide a verifiable list of default backends (in-memory / SQLite / external libraries); marked [To be verified].
5. Guardrail concurrency and timeout parameters: no specific concurrency cap or timeout default for parallel guardrail execution was found in official documentation; marked [To be verified].
6. Enterprise-deployment quantitative data: none of the four official cases published verifiable metrics such as cost reduction or success rates; no supplementation was done.
7. Details of Codex CLI integration with this platform: it belongs to the same OpenAI ecosystem, but no dedicated research was done this time; its Harness form will be handled in a separate article.

8. References

1. New tools for building agents — OpenAI, 2025-03-11。https://openai.com/blog/new-tools-for-building-agents
2. OpenAI Japanese official blog (same article, with full charts and pricing) — OpenAI, 2025。https://openai.com/ja-JP/index/new-tools-for-building-agents/
3. Assistants API (v2) FAQ — OpenAI Help Center。https://help.openai.com/zh-hans-cn/articles/8550641-assistants-api-v2-faq
4. OpenAI Launches New API, SDK, and Tools to Develop Custom Agents — InfoQ, 2025-03。https://www.infoq.com/news/2025/03/openai-responses-api-agents-sdk/
5. OpenAI Responses API & Agents SDK — Axevate Consulting (primitive breakdown and production issues)。https://axevate.com/ai/frameworks/openai-responses-api
6. How To Build Your First Production Ready Agent With OpenAI's Agents SDK And Responses API (2026 Guide) — Rahul Kolekar。https://rahulkolekar.com/how-to-build-your-first-production-ready-agent-with-openai-s-agents-sdk-and-responses-api-2026-guide/
7. Function calling and other API updates — OpenAI, 2023-06-13。https://openai.com/blog/function-calling-and-other-api-updates
8. Harness engineering: leveraging Codex in an agent-first world — OpenAI, 2026-02-11。https://openai.com/index/harness-engineering/
9. R01-Overview retrieval report (Responses API release milestone, AAIF founding) — this project's internal retrieval report。
10. Project parameter card v1.0 (six-layer capability model and conceptual boundaries) — this project's internal baseline document。