# Deep-Dive DD-11 — OpenAI Agents SDK: 2-Layer Harness/Compute Split **Course**: Master Course **Deep-Dive**: DD-11 **Duration**: 60 minutes **Level**: Senior Engineer and above **Prerequisites**: Modules 0–12; DD-01–10 (the harness roster to this point) > *The most architecturally thoughtful SDK. 2-layer harness/compute split. 7 sandbox providers. Handoffs + agents-as-tools. The SDK reference. Module 5 (Sandboxing): 5/5 — the highest-scoring sandbox in the roster.* --- ## Learning Objectives After this deep-dive, you will be able to: 1. State the OpenAI Agents SDK's defining contribution — the 2-layer harness/compute split — and explain why it makes credential isolation architectural rather than optional. 2. Name the 7 sandbox providers and explain why the provider abstraction makes the harness code provider-agnostic (swap by configuration, not code change). 3. Distinguish handoffs from agents-as-tools (Module 1.3) and explain why the SDK is the only framework in the roster that formalizes both as first-class primitives. 4. Score the SDK 38/60 and explain the shape: 5/5 on Module 5 (Sandboxing, the reference), 4/5 on Module 10 (Subagents, both patterns), low on observability and verification (bring-your-own layers). 5. Articulate the SDK-as-foundation thesis — the SDK bakes in the hardest architectural decisions (credential isolation, sandbox portability, subagent delegation) as defaults, so the harness you build on top starts from a strong foundation rather than a blank file. --- ## The Subject | Metric | Value | | --- | --- | | Category | SDK / primitives library (not a finished harness) | | Architecture | 2-layer harness/compute split | | Sandbox providers | 7 (local bash, Docker, E2B, Modal, Daytona, Cloudflare, Vercel) | | Subagent patterns | handoffs + agents-as-tools (both first-class) | | Contribution | The architectural foundation for building a custom harness | | Score | 38/60 — highest on Module 5 (Sandboxing, 5/5) and Module 10 (Subagents, 4/5) | The OpenAI Agents SDK is not a complete harness — it is 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 not in what it does out of the box (it does little); its value is in the **architectural decisions it bakes in as defaults** so that the harness you build on top of it starts from a strong foundation rather than a blank file. Three contributions define the SDK, and each maps to a course module. The 2-layer harness/compute split (Module 5) — the loop runs on your backend; tool execution runs in a sandbox the SDK manages, and the separation is architectural. The 7-provider sandbox abstraction (Module 5) — swap sandbox providers by configuration, so the harness code is provider-agnostic. And the handoffs + agents-as-tools pattern (Module 1.3) — both subagent patterns, formalized as first-class SDK primitives. This is the SDK-level realization of patterns the course teaches abstractly. If you want to understand what "good harness architecture" looks like as a starting point rather than an end product, the Agents SDK is the reference. --- ## Architecture — The 2-Layer Split The defining decision is that the harness and the compute live in different places, and the SDK enforces the boundary between them. **Harness layer** (your backend): the loop, the model calls, the orchestration logic, the handoff decisions. Runs wherever you deploy your application. This is where credentials live, where the model API key is held, where the reasoning happens. **Compute layer** (sandbox): tool execution. Managed by one of 7 providers. The SDK abstracts the provider — you swap by configuration, not by rewriting tool code. A tool that runs in local bash during development runs in E2B in production by changing a config value. This is Module 5's outside-sandbox architecture realized as an SDK design. The separation is **baked in** — you cannot accidentally put credentials in the sandbox because the SDK architecture does not provide a path for them to get there. Credential isolation is not a discipline you maintain; it is a property you inherit. This is the same principle as NemoClaw (DD-09): enforcement outside the agent's reach, applied to a different trust boundary — credentials outside the sandbox's reach. --- ## The 7-Provider Sandbox Abstraction Module 5 teaches inside-sandbox vs outside-sandbox. The Agents SDK makes outside-sandbox the default and abstracts the *where* of the sandbox behind a provider interface. The seven providers: local bash (development, no isolation), Docker (local/CI with container isolation), E2B (cloud sandboxes, per-session ephemeral VMs), Modal (serverless cloud execution), Daytona (development environment provisioning), Cloudflare (edge-proximate execution), Vercel (serverless functions, deploy-integrated). The architectural payoff: the harness code is **provider-agnostic.** You write the tool once. You target the provider by config. This is the most architecturally thoughtful sandboxing in the roster (5/5 on Module 5) because it treats the sandbox as a swappable runtime concern rather than a baked-in deployment decision. No other harness studied separates "what the tool does" from "where the tool runs" this cleanly. Compare to OpenCode (DD-03): OpenCode's client/server split enables sandboxing, but the sandbox is Docker-or-nothing. The Agents SDK's abstraction means a single harness can run in seven different isolation regimes without code change. A misconfigured weak regime (local bash in production) is a config error, not an architectural one — and config errors are easier to catch in review than architectural mistakes are to fix after deployment. --- ## Handoffs + Agents-as-Tools — Module 1.3 Formalized Module 1.3 describes two subagent patterns. **Handoffs**: one agent transfers control to another ("this is a database question, handing off to the DB agent"). The first agent stops; the second takes over the task. This is delegation by transfer. **Agents-as-tools**: one agent calls another as a tool ("ask the DB agent this question, return the answer"). The first agent retains control; the second is a capability it invokes. This is delegation by query. Most harnesses implement one or neither. The Agents SDK implements **both as first-class primitives** — you declare a handoff or an agents-as-tools relationship in agent definition, and the SDK handles the routing, context passing, and result return. This is the only framework in the roster where both Module 1.3 patterns are formalized rather than hand-rolled, which is why it scores 4/5 on subagents (Module 10). The orchestration model is **declarative-by-composition.** You define agents (each with a model, instructions, tools, and handoff targets), and the SDK runtime drives the loop, the handoffs, and the sandbox dispatch. You do not write the loop; you configure the agents and the SDK runs the loop for you. This sits between LangGraph's (DD-10) fully-declared-graph model and Pi's (DD-01) hand-written-loop model — the SDK gives you structure without forcing you to declare every edge. --- ## Score: 38/60 | Module | Score | Key decision | Notes | | --- | --- | --- | --- | | 1 Loop | 4 | SDK-driven, composable | the runtime drives; you compose | | 2 Tools | 3 | bring your own | framework provides the dispatch, not the tools | | 3 Context | 3 | standard | you manage context strategy | | 4 Memory | 3 | bring your own | no built-in store | | 5 Sandbox | 5 | 7-provider abstraction | highest-scoring sandbox in the roster | | 6 Permission | 4 | approvals as first-class | handoffs + approvals integrated | | 7 Errors | 3 | standard | framework-level | | 8 State | 3 | bring your own | no built-in checkpointing | | 9 Verification | 2 | limited | you add gates | | 10 Subagents | 4 | handoffs + agents-as-tools | both Module 1.3 patterns, first-class | | 11 Observability | 2 | bring your own | no built-in tracing | | 12 Prompt | 3 | per-agent instructions | you assemble | | **TOTAL** | **38/60** | | | Highest on Module 5 (Sandboxing): 5/5 — the 7-provider abstraction is the most architecturally thoughtful sandboxing in the roster. Also strong on Module 1.3 / Module 10 (Subagents): 4/5 — handoffs + agents-as-tools as first-class patterns, the only framework that formalizes both. The low scores (observability 2, verification 2) reflect that this is an SDK, not a finished harness — you bring those layers yourself. ### Architect's Verdict > *The OpenAI Agents SDK optimizes for architectural clarity — the 2-layer harness/compute split, the 7-provider sandbox abstraction, and handoffs + agents-as-tools as first-class primitives. It is an SDK, not a finished harness — you build the harness WITH it, not on top of a finished product. The payoff is that the hardest architectural decisions (credential isolation, sandbox portability, subagent delegation) are made for you as defaults rather than discovered as mistakes. Build on it when you want the strongest architectural foundation for a custom harness, especially for multi-tenant or multi-sandbox deployments where swapping isolation regimes by configuration matters.* ### MLSecOps Relevance > *The 2-layer split makes credential isolation architectural, not optional — you cannot accidentally put credentials in the sandbox because the SDK architecture prevents it. This is the SDK-level realization of Module 5's credential boundary: where NemoClaw (DD-09) enforces policy outside the agent's reach, the Agents SDK enforces credential isolation outside the sandbox's reach. Both are the same principle applied to different trust boundaries. The 7-provider abstraction also means isolation is never a deployment afterthought — you pick the regime at config time, and a misconfigured weak regime (local bash in production) is a config error, not an architectural one.* ### Three things the SDK does better 1. **7-provider sandbox abstraction**: swap providers by config; the harness code is provider-agnostic. The most architecturally thoughtful sandboxing in the roster (5/5 on Module 5). 2. **Handoffs + agents-as-tools as first-class patterns**: both Module 1.3 subagent patterns formalized as SDK primitives — the only framework that does both, rather than leaving you to hand-roll one. 3. **2-layer split baked in**: credential isolation is architectural, not optional. The SDK gives you a correct default where most harnesses give you a footgun. ### Three things to fix 1. **It is an SDK — you must build the harness yourself.** No batteries included: tools, memory, observability, verification are all bring-your-own. The Agents SDK is a foundation, not a product. 2. **The 7-provider abstraction adds a learning curve.** Which provider for which use case? The right answer depends on isolation requirements, latency budget, and deployment target — a decision the SDK surfaces rather than resolves. 3. **No built-in observability.** You bring your own tracing (Module 11). For a harness built on the SDK, this is the first thing to add — a harness without observability is un-debuggable on long runs. --- ## Anti-Patterns ### Treating the SDK as a finished harness The SDK is primitives, not a product. If you deploy it as-is, you have a loop and a sandbox but no memory, no observability, no verification gates. Cure: treat the SDK as a foundation. Before deploying, add the bring-your-own layers: memory (Module 4), observability/tracing (Module 11), verification gates (Module 9). The SDK gives you the hardest architectural decisions as defaults; you add the operational layers. ### Choosing a sandbox provider without matching the isolation regime to the deployment A common error is to pick local bash for development and forget to switch to a real isolation provider (E2B, Docker, Modal) for production. The result is an agent running tools on the host with no isolation — the Module 5 footgun. Cure: treat the sandbox provider as a deployment-time decision gated by environment. Local bash in dev, E2B or Docker in production. The abstraction makes swapping trivial; the discipline is in not forgetting. ### Using handoffs when agents-as-tools would preserve visibility Handoffs transfer control — the parent agent stops, and visibility into the task is lost. For tasks where the parent should retain oversight (the DB agent answers a question, but the parent continues orchestrating), agents-as-tools is the right pattern. Cure: default to agents-as-tools for query-style delegation; use handoffs only for genuine transfer (the DB agent owns the task to completion). The SDK offers both because different tasks need different control models. --- ## Key Terms | Term | Definition | | --- | --- | | **2-layer split** | Harness layer (loop, model calls, credentials) runs on your backend; compute layer (tool execution) runs in a sandbox. The SDK enforces the boundary — credentials cannot cross it. | | **7-provider abstraction** | A uniform interface across 7 sandbox providers (local bash, Docker, E2B, Modal, Daytona, Cloudflare, Vercel). Swap by configuration, not code change. Module 5 reference. | | **Credential isolation (architectural)** | Credentials cannot enter the compute layer because the SDK provides no path for them. Not a policy; a structural impossibility — the same principle as NemoClaw's governance-beneath-the-agent. | | **Handoff** | A subagent pattern (Module 1.3): one agent transfers control to another. Delegation by transfer — the parent stops, the subagent takes over. | | **Agents-as-tools** | A subagent pattern (Module 1.3): one agent calls another as a tool. Delegation by query — the parent retains control, the subagent returns a structured result. | | **Declarative-by-composition** | The SDK's orchestration model: you define agents (model, instructions, tools, handoff targets); the runtime drives the loop. Structure without forcing you to declare every edge. | --- ## Lab Exercise See `07-lab-spec.md`. You simulate the OpenAI Agents SDK's 2-layer split: a harness layer (loop, model calls, credentials) and a compute layer (sandbox with swappable providers). You confirm credentials cannot cross the boundary, swap providers by configuration, and demonstrate both subagent patterns (handoffs and agents-as-tools). --- ## References 1. **OpenAI Agents SDK documentation** — the 2-layer + 7-provider reference. 2. **Module 1** — the loop; the SDK-driven orchestration model. 3. **Module 1.3** — handoffs + agents-as-tools; the two subagent patterns the SDK formalizes. 4. **Module 5** — outside-sandbox architecture; the 7-provider model; credential isolation as an architectural property. 5. **Module 10** — subagents; the SDK's handoffs + agents-as-tools as the Module 1.3 realization. 6. **Module 11** — observability; the layer you must add yourself (the SDK does not provide it). 7. **DD-03 (OpenCode)** — the client/server comparison; a different realization of the harness/compute split (Docker-or-nothing vs 7-provider abstraction). 8. **DD-04 (Codex CLI)** — the sibling; the other OpenAI-camp harness, compared on the finished-product vs SDK axis. 9. **DD-09 (NemoClaw)** — the same trust-boundary principle applied to a different layer (governance outside the agent's reach vs credentials outside the sandbox's reach). 10. **DD-10 (LangGraph)** — the orchestration-framework contrast; LangGraph declares the graph, the Agents SDK composes the agents. The two frameworks you would pair.