OpenAI Agents SDK
2-Layer Harness/Compute Split · Deep-Dive DD-11 · Course 1
60 minutes · SDK / primitives library · The architectural foundation for a custom harness
Not a finished harness — the primitives for building one. Where Pi (DD-01) is a harness you run and Claude Code is a harness you configure, the Agents SDK is a kit you assemble with. Its value is the architectural decisions it bakes in as defaults.
Deep-Dives · The Harness Roster
The thesis — primitives, not product
A FINISHED HARNESS (Pi, DD-01)
You run it. The loop, tools, memory, observability are all there. You configure, you don't build.
AN SDK (OpenAI Agents SDK)
You build the harness WITH it. The hardest architectural decisions are defaults. You add the operational layers (memory, observability, verification) yourself.
The value is the defaults, not the surface. Three contributions define the SDK: the 2-layer harness/compute split (Module 5), the 7-provider sandbox abstraction (Module 5), and handoffs + agents-as-tools as first-class primitives (Module 1.3). Each bakes in a decision most harnesses leave you to discover as a mistake.
The 2-layer split — credential isolation as architecture
HARNESS LAYER (your backend)
Loop, model calls, orchestration, handoff decisions. Credentials held here. Runs wherever you deploy your application.
COMPUTE LAYER (sandbox)
Tool execution only. Managed by one of 7 providers. No code path for credentials to enter. Isolation is structural, not a policy.
You cannot accidentally put credentials in the sandbox because the SDK architecture prevents it. The separation is baked in. This is Module 5's outside-sandbox architecture realized as an SDK design — a discipline you maintain converted into a property you inherit.
The 7-provider sandbox abstraction — Module 5 reference (5/5)
local bash
dev · no isolation
Docker
local/CI · container
E2B
cloud · ephemeral microVM
Daytona
dev env provisioning
Cloudflare
edge-proximate
Plus Vercel (serverless, deploy-integrated). The harness code is provider-agnostic — swap by configuration, not code change. This is the most architecturally thoughtful sandboxing in the roster. Compare to OpenCode (DD-03): Docker-or-nothing. A misconfigured weak regime (local bash in production) is a config error, not an architectural one.
Handoffs + agents-as-tools — Module 1.3 formalized
AGENTS-AS-TOOLS (query)
Parent calls subagent like a tool. Sync, retains control. Gets structured result, continues orchestrating. Use for query-style delegation.
HANDOFFS (transfer)
Parent transfers control. Terminal. Subagent owns the task to completion. Parent stops. Use for genuine transfer.
The SDK is the only framework in the roster that formalizes both as first-class primitives rather than hand-rolled. Most harnesses implement one or neither. This is the load-bearing reason for the 4/5 on Module 10 (Subagents) — the SDK-level realization of Module 1.3.
Same principle, different layer — the NemoClaw connection
NEMOCLAW (DD-09)
Governance gate is OUTSIDE the agent's reach. The agent proposes; the harness enforces. The gate is structurally unreachable from the agent.
AGENTS SDK (DD-11)
Credentials are OUTSIDE the sandbox's reach. The sandbox executes; the harness holds creds. Credentials are structurally inaccessible from the sandbox.
Same architectural principle applied to a different trust boundary. Enforcement outside the principal's reach. Both convert a discipline you maintain (don't bypass the gate; don't leak credentials) into a property you inherit. This is the cross-cutting pattern the course wants you to internalize.
Declarative-by-composition — the orchestration model
LANGGRAPH (DD-10)
Declare the whole graph up front. Nodes, edges, conditional routing. Maximum structure, maximum ceremony.
AGENTS SDK
Compose agents. Declare handoffs and tools. The SDK runtime drives the loop. Structure without forcing every edge.
PI (DD-01)
Hand-write the loop. You own the ReAct cycle, the context, the dispatch. Maximum control, maximum effort.
You define agents (model, instructions, tools, handoff targets); the SDK runtime drives the loop, routes handoffs, dispatches to sandboxes. You never see the loop code. The Agents SDK sits in the middle of the orchestration spectrum.
The score profile — 38/60, SDK-specialist shape
| Module | Score | Key decision |
|---|
| 5 Sandbox | 5/5 | 7-provider abstraction (reference, highest in roster) |
| 1 Loop | 4/5 | SDK-driven, composable |
| 6 Permission | 4/5 | approvals as first-class |
| 10 Subagents | 4/5 | handoffs + agents-as-tools (both Module 1.3) |
| 2 Tools | 3/5 | bring your own |
| 4 Memory | 3/5 | bring your own |
| 9 Verification | 2/5 | you add gates |
| 11 Observability | 2/5 | bring your own tracing |
| TOTAL | 38/60 | SDK-specialist: max on architecture, bring-your-own on operations |
Read the score as a profile, not a ranking. The 5/5 on Module 5 and the 2/5 on observability are the same design decision — the SDK bakes in architecture and leaves operations to you.
Anti-patterns
Treating the SDK as a finished harness. It is primitives. Deploy it as-is and you have a loop and a sandbox but no memory, no observability, no verification gates. Cure: treat it as a foundation; add the bring-your-own layers before deploying.
Choosing a sandbox provider without matching the isolation regime to the deployment. Local bash in dev, forgetting to switch to E2B/Docker in production — the Module 5 footgun. Cure: gate the provider by environment; treat it as a deployment-time decision.
Using handoffs when agents-as-tools would preserve visibility. Handoffs are terminal — the parent loses oversight. For query-style delegation, agents-as-tools is the right pattern. Cure: default to agents-as-tools; reserve handoffs for genuine transfer.
What you can now do
- State the SDK's defining contribution — the 2-layer harness/compute split — and explain why credential isolation is architectural rather than optional.
- Name the 7 sandbox providers and explain why the abstraction makes the harness code provider-agnostic (swap by config, not code change).
- Distinguish handoffs from agents-as-tools and explain why the SDK is the only framework that formalizes both as first-class primitives.
- Score the SDK 38/60 and defend the shape: 5/5 on Module 5 (reference), 4/5 on Module 10, low on observability and verification.
- Articulate the NemoClaw connection — same principle (enforcement outside the principal's reach), different trust boundary.
The lab: simulate the SDK's 2-layer split, confirm credentials cannot cross the boundary, swap providers by configuration, and demonstrate both subagent patterns (handoffs and agents-as-tools).
Next: DD-12 — CrewAI: The multi-agent framework (the emergent-coordination pole)