# Teaching Script — DD-11: OpenAI Agents SDK (2-Layer Harness/Compute Split) **Course**: Master Course · **Deep-Dive**: DD-11 · **Duration**: 60 minutes · **Audience**: Senior Engineer and above **Slides**: `03-slide-deck.html` (10 slides) > *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.* --- ## [SLIDE 1] Title — OpenAI Agents SDK Welcome back. We are at DD-11, the OpenAI Agents SDK. Over the last ten deep-dives you have studied harnesses — Pi is a harness you run, Claude Code is a harness you configure, Hermes is a harness with a memory system, NemoClaw is a harness with governance. Today we study something different. The OpenAI Agents SDK is not a harness. It is the primitives for building one. This distinction matters. Where the other deep-dives ask "how does this harness solve a problem," this one asks "what architectural decisions does this SDK bake in as defaults so that the harness you build on top starts from a strong foundation rather than a blank file?" That is the framing. Sixty minutes. Let's go. ## [SLIDE 2] The thesis — primitives, not product The defining insight is on the screen. A finished harness — like Pi, DD-01 — gives you the loop, the tools, the memory, the observability. You configure it. You do not build it. The Agents SDK gives you the opposite. It gives you primitives — the loop mechanism, the tool dispatch, the sandbox interface, the subagent routing — and you assemble a harness with them. Now here is the subtle point. The value of the SDK is not in what it does out of the box. Out of the box it does very little. The value is in the architectural decisions it bakes in as defaults. Three contributions define the SDK, and each maps to a course module. The 2-layer harness/compute split — that is Module 5, sandboxing. The 7-provider sandbox abstraction — also Module 5. And handoffs plus agents-as-tools as first-class primitives — that is Module 1.3, the subagent patterns. Here is why this matters. Most harnesses leave you to discover the hardest architectural decisions as mistakes. You put credentials in the sandbox and get a leak. You bake in one sandbox provider and cannot migrate. You hand-roll one subagent pattern and discover you needed the other. The SDK makes those decisions for you, as defaults. You start from a foundation, not a footgun. That is the pitch. ## [SLIDE 3] The 2-layer split — credential isolation as architecture The defining decision is on the screen. The harness layer runs on your backend — the loop, the model calls, the orchestration logic, the handoff decisions. The credentials live here. The compute layer is a sandbox where tool execution happens, managed by one of seven providers. The SDK draws a hard boundary between them. Here is the key phrase: you cannot accidentally put credentials in the sandbox because the SDK architecture prevents it. There is no code path for credentials to cross that boundary. This is Module 5's outside-sandbox architecture realized as an SDK design. In a single-layer harness — where the loop and the tool execution share an address space — credentials are, by default, visible to the model. You have to add discipline to keep them out. You have to maintain that discipline over the life of the project. The 2-layer split converts that discipline into a property. You inherit credential isolation. You do not maintain it. That is the difference between architectural and optional, and it is the load-bearing distinction of this deep-dive. We will come back to it when we connect to NemoClaw. ## [SLIDE 4] The 7-provider sandbox abstraction — Module 5 reference Now the second contribution — and this is where the SDK earns its 5-out-of-5 on Module 5, the highest sandboxing score in the entire roster. Seven providers behind a uniform abstraction. Local bash for development, no isolation. Docker for local or CI with container isolation. E2B for cloud sandboxes with ephemeral microVMs. Modal for serverless cloud execution. Daytona for dev-environment provisioning. Cloudflare for edge-proximate execution. And Vercel for serverless functions with deploy integration. The architectural payoff is on the screen. The harness code is provider-agnostic. You write the tool once. You target the provider by configuration. A tool that runs in local bash during development runs in E2B in production by changing a config value. Compare to OpenCode, DD-03. OpenCode's client/server split enables sandboxing — good architectural instinct — 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. Now here is the security argument. A misconfigured weak regime — local bash accidentally left on in production — is a config error. Config errors are caught in review. Architectural mistakes are discovered after deployment, when they become incidents. The abstraction moves a whole class of mistake from the architectural column to the config column, and that is a security win. ## [SLIDE 5] Handoffs + agents-as-tools — Module 1.3 formalized The third contribution. Module 1.3 describes two subagent patterns. Handoffs — one agent transfers control to another. The first agent stops, the second takes over the task. This is delegation by transfer. And agents-as-tools — one agent calls another as a tool. The first agent retains control, the second is a capability it invokes and gets a structured result back. This is delegation by query. Here is the load-bearing claim: the Agents SDK is the only framework in the roster that formalizes both as first-class primitives. Most harnesses implement one or neither. You declare a handoff or an agents-as-tools relationship in agent definition, and the SDK handles the routing, the context passing, and the result return. You do not hand-roll either pattern. Why does this matter? Different tasks need different control models. If you are asking the DB agent a question and continuing — agents-as-tools. The parent retains visibility. If you are handing off the whole task to the DB agent to own — handoffs. The parent transfers and stops. The SDK offers both because the course teaches both in Module 1.3, and the SDK is the framework that took that lesson seriously. That is the 4-out-of-5 on Module 10. ## [SLIDE 6] Same principle, different layer — the NemoClaw connection Now the connection I flagged at the start. NemoClaw, DD-09, and the OpenAI Agents SDK, DD-11, apply the same architectural principle to different trust boundaries. This is one of the load-bearing cross-references in the course, so let me be precise. In NemoClaw, the governance gate sits between the agent's proposal and the action that executes. The agent proposes, the harness validates, the action runs. The agent cannot bypass the gate because the gate is not in the agent's address space — it is in the harness layer, beneath the agent. The gate is structurally unreachable. In the Agents SDK, the credential boundary sits between the sandbox and the credentials. The sandbox executes tools, the harness holds the credentials. The sandbox cannot reach the credentials because the credentials live in the harness layer, outside the sandbox's address space. The credentials are structurally inaccessible. Same principle. 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. The gate is structurally unreachable; the credentials are structurally inaccessible. This is the cross-cutting pattern the course wants you to internalize. When you see it in one place, you should look for it in others. Trust boundaries that are structural, not policy-based, are the architectural move. ## [SLIDE 7] Declarative-by-composition — the orchestration model Now let me position the SDK on the orchestration spectrum, because there are three frameworks you should hold in your head together. On the left, LangGraph, DD-10 — declare the whole graph up front. Nodes, edges, conditional routing. Maximum structure, maximum ceremony. You declare every edge. In the middle, the Agents SDK. You compose agents. You declare each agent with its model, instructions, tools, and handoff targets. You declare the delegation relationships. The SDK runtime drives the loop, routes the handoffs, dispatches to sandboxes. You never see the loop code. Structure without forcing you to declare every edge. On the right, Pi, DD-01 — hand-write the loop. You own the ReAct cycle, the context management, the dispatch. Maximum control, maximum effort. The SDK sits in the middle and it is the right answer for a specific situation: when you want the architectural foundation — the 2-layer split, the sandbox abstraction, the subagent primitives — but you do not want the ceremony of declaring a full graph. You compose agents, the runtime drives. That is declarative-by-composition. ## [SLIDE 8] The score profile — 38/60, SDK-specialist shape Now the score. 38 out of 60. Highest on Module 5, sandboxing, at 5-out-of-5 — the 7-provider abstraction is the most architecturally thoughtful sandboxing in the roster. Also strong on Module 10, subagents, at 4-out-of-5 — handoffs plus agents-as-tools, both formalized. And Module 1, loop, at 4-out-of-5 — SDK-driven and composable. Module 6, permission, at 4-out-of-5 — approvals as first-class. The low scores tell you what the SDK does not do. Module 9, verification, 2-out-of-5 — you add the gates. Module 11, observability, 2-out-of-5 — bring your own tracing. Module 4, memory, 3-out-of-5 — bring your own store. Module 2, tools, 3-out-of-5 — bring your own. Read the score as a profile, not a ranking. The 5-out-of-5 on Module 5 and the 2-out-of-5 on observability are the same design decision — the SDK bakes in architecture and leaves operations to you. This is the SDK-specialist shape. If you wanted a finished product you would not be here; you are here because you want the strongest architectural foundation and you are willing to add the operational layers yourself. ## [SLIDE 9] Anti-patterns Three anti-patterns to avoid. First: treating the SDK as a finished harness. It is primitives. If you deploy it as-is, you have a loop and a sandbox but no memory, no observability, no verification gates. The cure is to treat the SDK as a foundation. Before deploying, add the bring-your-own layers: memory from Module 4, observability and tracing from Module 11, verification gates from Module 9. Second: choosing a sandbox provider without matching the isolation regime to the deployment. The classic mistake is to pick local bash for development and forget to switch to E2B or Docker for production. The result is an agent running tools on the host with no isolation — the Module 5 footgun. The cure is to treat the 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. Third: using handoffs when agents-as-tools would preserve visibility. Handoffs are terminal — the parent loses oversight of the task. For query-style delegation, where the parent should continue orchestrating, agents-as-tools is the right pattern. Default to agents-as-tools; reserve handoffs for genuine transfer. ## [SLIDE 10] What you can now do Let's close. After this deep-dive, you can state the SDK's defining contribution — the 2-layer harness/compute split — and explain why credential isolation is architectural rather than optional. You can name the 7 sandbox providers and explain why the abstraction makes the harness code provider-agnostic. You can distinguish handoffs from agents-as-tools and explain why the SDK is the only framework that formalizes both as first-class primitives. You can score the SDK 38 out of 60 and defend the shape. And you can articulate the NemoClaw connection — same principle, different trust boundary. The lab simulates the SDK's 2-layer split in pure Python. You confirm credentials cannot cross the boundary, swap providers by configuration, and demonstrate both subagent patterns. That is the work. Next is DD-12, CrewAI — the multi-agent framework, and the emergent-coordination pole that pairs with LangGraph's declared coordination. We will draw that contrast explicitly. See you there. --- *End of teaching script. Approximate word count: 2100 words. Pair with slides 1-10 in `03-slide-deck.html`.*