Before Adopting OpenAI Agents SDK, Write the Runtime Contract First

OpenAI Agents SDK is easy to misread as a faster way to build "more agents." That is the shallow interpretation. The more useful reason to evaluate it is that it puts agents, tools, handoffs, guardrails, sessions, tracing, sandbox execution, and human approval into one Python SDK surface. That gives a team a chance to move agent workflows from prompt scripts into inspectable engineering units.

But that also changes the adoption question. Do not start by asking how many agents you can chain together. Start with the harder question: when an agent can call tools, delegate to another agent, preserve session history, enter a sandbox, and emit traces, who owns each step and how will a failure be reconstructed?

Doramagic project page: https://doramagic.ai/en/projects/openai-agents-python/

Doramagic manual: https://doramagic.ai/en/projects/openai-agents-python/manual/

Upstream project: https://github.com/openai/openai-agents-python

What is verified

On 2026-07-08 Bangkok time, there was no previous local daily-publish-* artifact for openai-agents-python. The Doramagic English and Chinese project/manual pages returned HTTP 200. The PROJECT_PACK was reachable and listed the expected assets, including quick start, prompt preview, human manual, AI context pack, boundary risk card, pitfall log, repo inspection, capability contract, evidence index, and claim graph.

The upstream repository is active. GitHub API data collected on 2026-07-08 showed 27,726 stars, 4,272 forks, 65 open issues, MIT license, a push timestamp of 2026-07-07T23:47:16Z, and an update timestamp of 2026-07-08T03:16:59Z. The latest GitHub release was v0.18.0, published on 2026-07-07T06:01:55Z.

The package metadata matters. pyproject.toml declares openai-agents version 0.18.0, Python >=3.10, MIT license, and dependencies including openai>=2.36.0,<3, pydantic>=2.12.2,<3, requests, websockets, and mcp>=1.19.0,<2. Optional extras cover voice, realtime, Redis, SQLAlchemy, Dapr, MongoDB, and several sandbox/provider integrations.

The local smoke test exposed a practical adoption boundary. The default macOS python3 on this machine is 3.9.6, and pip refused to install openai-agents==0.18.0 because the package requires Python >=3.10. Using python3.12 in an isolated venv succeeded, and Agent and Runner imported correctly. The first step is not writing an agent. The first step is pinning the runtime.

Do not start with multi-agent architecture

Multi-agent workflows create a tempting illusion: if the task is split into several roles, the system must be more capable. In engineering practice, more roles usually mean more state ownership, tool permission, handoff criteria, failure recovery, trace evidence, and accountability to define.

I would start with one agent and one low-risk tool. That tool should have three properties:

• Serializable inputs and outputs, so traces are useful.
• No production write permission, so the first trial cannot mutate real state.
• Clear failure modes, such as timeout, empty result, permission denial, or schema mismatch.

After that works, add a second agent. The second agent should not be a vague "expert." It should own one verifiable responsibility: reviewing a tool output, generating test cases, deciding whether human approval is required, or classifying a failure.

The runtime contract matters more than the quickstart

The README lists the core concepts clearly: Agents, Sandbox Agents, Agents as tools / Handoffs, Tools, Guardrails, Human in the loop, Sessions, Tracing, and Realtime Agents. The real implementation work is turning those concepts into a team contract.

For each agent workflow, I would require at least eight decisions:

• Tool boundary: which tools the agent can call, and which are read-only or write-capable.
• Handoff owner: who owns the final answer after delegation, and whether the original agent can still modify it.
• Session scope: whether session history belongs to a user, task, workspace, or run.
• Guardrail action: whether a guardrail failure means reject, retry, degrade, ask for human approval, or file an incident.
• Trace retention: how long traces are kept, who can see them, and whether they contain private data or secret fragments.
• Sandbox permission: which directories are readable, whether network is allowed, whether shell commands are allowed, and whether patches can be written back.
• Human approval: which actions require a person, such as publishing, deleting files, sending email, payment, or production config changes.
• Recovery rule: where a failed run resumes and whether previous tool outputs can be reused.

Without that contract, the SDK can only help you create unexplained agent behavior faster.

Sandbox Agents are useful, but not magic safety

Sandbox Agents are an important signal in the README. They move the agent from "answer a question" toward "do work inside a controlled computing environment." That is useful for repository inspection, command execution, patch generation, and long-running task state.

But a sandbox is not automatically safe. It is a boundary. The boundary still has to be designed.

For a first sandbox trial, I would not connect real repository write access. A better sequence is:

1. Mount a read-only demo repository and ask the agent to summarize the README and file structure.
2. Allow writing only inside a temporary directory.
3. Allow running tests, while recording command, exit code, stdout, and stderr.
4. Allow generating a patch, but let a human or CI decide whether to apply it.
5. Only then discuss write permission.

This sequence is slower, but it avoids a common false positive: "the agent changed files, therefore the system works." The better questions are what changed, why it changed, whether the trace proves it, and whether the next run can inherit bad state.

Recent issues show where to evaluate

Recent open issues are useful signals. They do not necessarily block adoption, but they show where evaluation should be strict:

• Session history retrieval may need run/turn awareness rather than only item limits.
• Sandbox provider expansion is still active.
• Eager tool dispatch shows that overlapping tool execution with model streaming is still an engineering frontier.
• Stable public access to the underlying function on FunctionTool is still being discussed.

Together, these point to one conclusion: do not only test the hello world. Test whether critical context disappears after session truncation, whether responsibility is traceable after handoff, whether schema changes fail loudly, and whether sandbox permissions stay consistent when the provider changes.

The minimal path I would use

First, pin Python. This smoke test showed that python3.9 fails while python3.12 installs and imports successfully. Write Python >=3.10 into the project setup, ideally with uv or a fixed venv.

Second, build one agent, one tool, and no production write permission. The output should include a trace id, tool input, tool output summary, guardrail result, and final answer.

Third, add failure cases before adding more agents. Test tool timeout, empty output, tool exception, and a user request that exceeds permission.

Fourth, introduce handoff only after the single-agent path is observable. Handoff acceptance should not be "another agent answered." It should be "the trace shows why delegation happened, what context moved, and who owns the final output."

Fifth, if you use Sandbox Agents, start with a read-only repository and a temporary directory. Do not give the first trial access to production repositories, secret directories, publishing accounts, or paid API actions.

Conclusion

OpenAI Agents SDK is worth serious evaluation because it is not a single capability. It is a set of agent runtime primitives: tools, handoffs, guardrails, sessions, tracing, sandbox execution, human approval, and realtime workflows. The value is not that a team can look more "multi-agent." The value is that agent workflows can become auditable, constrained, and recoverable.

My adoption recommendation is direct: write the runtime contract before scaling the number of agents. Make one agent stable, traceable, and recoverable on a low-risk tool. Then expand to handoffs and sandbox execution. Running the quickstart is the entrance. Explaining every tool call and every recovery path is the beginning of production readiness.

Source note: this post is based on Doramagic's openai-agents-python project/manual pages, the Doramagic PROJECT_PACK, upstream README, pyproject.toml, GitHub API data, and a local Python 3.9 / 3.12 installation smoke test completed on 2026-07-08 Bangkok time.