Course: Master Course · Deep-Dive: DD-11 · Duration: 60 min · Prerequisites: Modules 0–12, DD-01–10
The most architecturally thoughtful SDK. 2-layer harness/compute split. 7 sandbox providers. Handoffs + agents-as-tools. The SDK reference.
| 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 |
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:
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.
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) │
│ │
│ loop ──► model.complete() ──► tool_use? │
│ │ │
│ ▼ │
│ [SDK sandbox boundary] │
│ │ │
│ ─────────────────────────────────────┼─────────────────── │
│ COMPUTE LAYER (sandbox) │ │
│ ▼ │
│ one of 7 providers: │
│ local bash / Docker / E2B / Modal / │
│ Daytona / Cloudflare / Vercel │
│ (swap by configuration) │
│ │
│ credentials NEVER cross this boundary by construction │
└─────────────────────────────────────────────────────────── ┘
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.
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:
| Provider | When you use it |
|---|---|
| local bash | development; no isolation needed |
| 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.
Module 1.3 describes two subagent patterns:
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.
The SDK's 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.
| 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.
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.
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.
# Deep-Dive DD-11 — OpenAI Agents SDK: 2-Layer Harness/Compute Split
**Course**: Master Course · **Deep-Dive**: DD-11 · **Duration**: 60 min · **Prerequisites**: Modules 0–12, DD-01–10
> *The most architecturally thoughtful SDK. 2-layer harness/compute split. 7 sandbox providers. Handoffs + agents-as-tools. The SDK reference.*
---
## 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 |
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:
1. The **2-layer harness/compute split** (Module 5) — the loop runs on your backend; tool execution runs in a sandbox the SDK manages. The separation is architectural, not optional.
2. The **7-provider sandbox abstraction** (Module 5) — swap sandbox providers by configuration. The harness code is provider-agnostic.
3. 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) │
│ │
│ loop ──► model.complete() ──► tool_use? │
│ │ │
│ ▼ │
│ [SDK sandbox boundary] │
│ │ │
│ ─────────────────────────────────────┼─────────────────── │
│ COMPUTE LAYER (sandbox) │ │
│ ▼ │
│ one of 7 providers: │
│ local bash / Docker / E2B / Modal / │
│ Daytona / Cloudflare / Vercel │
│ (swap by configuration) │
│ │
│ credentials NEVER cross this boundary by construction │
└─────────────────────────────────────────────────────────── ┘
```
- **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.
## 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:
| Provider | When you use it |
| --- | --- |
| local bash | development; no isolation needed |
| 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.
## 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.
## Orchestration Model
The SDK's 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.*
### 3 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.
### 3 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 10). For a harness built on the SDK, this is the first thing to add — a harness without observability is un-debuggable on long runs.
---
## 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** — observability; the layer you must add yourself (the SDK does not provide it).
6. **DD-03 (OpenCode)** — the client/server comparison; a different realization of the harness/compute split (Docker-or-nothing vs 7-provider abstraction).
7. **DD-04 (Codex CLI)** — the sibling; the other OpenAI-camp harness, compared on the finished-product vs SDK axis.
8. **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).
9. **DD-10 (LangGraph)** — the orchestration-framework contrast; LangGraph declares the graph, the Agents SDK composes the agents.