D4 · Designing and Building Agentic Systems

This domain shares top weight with the Responses API – roughly 11 of 60 items (18%) – and mirrors the Academy Design and Build Agentic Systems course (110 min, the longest API course). It tests whether you can choose among the three agent runtimes, give an agent tools and boundaries, orchestrate multiple agents or subagents, add guardrails and approvals, observe it with tracing, and respect the constraints of the managed Agents API. The single most-tested distinction is which runtime for which problem.

What you need to know

An agent is a model with instructions, tools and a loop that lets it act, observe and continue toward a goal. OpenAI gives you three ways to run one: the Responses API + tools where you own the loop; the open-source Agents SDK you run yourself for code-first orchestration; and the Agents API where OpenAI runs a managed Codex harness – sessions, orchestration, context compaction and recovery – while you supply tools and pick the environment. Agents work in sessions inside an environment (hosted or self-hosted sandbox), use tools including MCP connections, can delegate to subagents, and need guardrails, approvals and tracing. The Agents API is US-data-residency-only with no ZDR, and a self-hosted sandbox does not change that.

Learning objectives

By the end of this page you should be able to:

1. Choose the right runtime – Responses + tools, Agents SDK, or Agents API – for a given problem.
2. Explain sessions, environments and hosted vs self-hosted sandboxes.
3. Give an agent tools, including MCP connections, safely.
4. Design multi-agent systems and subagent delegation.
5. Add guardrails, approvals, and human-in-the-loop controls.
6. Use tracing and observability, and respect the Agents API constraints.

4.1 The three runtimes

This is the heart of the domain. Learn the table cold.

Do you need OpenAI to run and recover a durable, long session for you?
        │
   ┌────┴─────────────────────────┐
   │ Yes                          │ No
   ▼                              ▼
 Agents API (managed harness)   Do you want a framework for
 hosted/self-hosted sandbox,    code-first orchestration you run?
 subagents, compaction              │
                            ┌───────┴────────┐
                            │ Yes            │ No
                            ▼                ▼
                       Agents SDK       Responses API + tools
                       (you run it)     (you own the loop)

4.2 Building an agent in the Agents SDK

from agents import Agent, Runner, function_tool

@function_tool
def lookup_order(order_id: str) -> dict:
    return orders_db.get(order_id)

support_agent = Agent(
    name="Support",
    instructions="Help with orders. Use tools; never invent an order.",
    model="gpt-5.6-terra",
    tools=[lookup_order],
)

result = Runner.run_sync(support_agent, "Where is order 8842?")
print(result.final_output)

import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const lookupOrder = tool({
  name: 'lookup_order',
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => ordersDb.get(orderId),
});

const supportAgent = new Agent({
  name: 'Support',
  instructions: 'Help with orders. Use tools; never invent an order.',
  model: 'gpt-5.6-terra',
  tools: [lookupOrder],
});

const result = await run(supportAgent, 'Where is order 8842?');
console.log(result.finalOutput);

4.3 Starting an Agents API session

The Agents API is a beta surface; you opt in with a header and OpenAI runs the harness.

POST /v1/agents/sessions
OpenAI-Beta: agents=v1
{
  "agent": {
    "model": "gpt-5.6-terra",
    "instructions": "Migrate the test suite to the new framework.",
    "tools": [{ "type": "shell" }],
    "mcp_servers": [{ "url": "https://mcp.internal/repo" }]
  },
  "environment": { "type": "hosted" },
  "multi_agent": { "enabled": true, "max_concurrent_subagents": 3 }
}

You then follow progress via streaming or webhooks, and steer or continue the session. OpenAI handles orchestration, context summarisation, subagent delegation, and session resumption.

4.4 Sessions and environments

Hosted vs self-hosted sandbox: a hosted sandbox is OpenAI-run (billed at container rates) and simplest; a self-hosted sandbox runs in your infrastructure for control over the execution environment. Crucially, self-hosting the sandbox does not change the Agents API residency/ZDR constraints – see 4.8.

4.5 Tools and MCP

Agents act through tools: function calling, web search, file search, code interpreter, shell, computer use, image generation, apply patch, and MCP connections that expose external systems as tools. MCP lets an agent reach a database, a repo, or a SaaS system through a standard protocol instead of bespoke glue.

4.6 Multi-agent and subagents

Two patterns solve different problems:

Subagents in the managed harness let the lead delegate concurrent work and gather results; keep max_concurrent_subagents bounded so cost and rate limits stay predictable.

4.7 Guardrails, approvals and tracing

An agent that can take irreversible actions needs an approval gate on those actions and tracing so you can see what it did and why.

4.8 Agents API constraints

Know these – they are frequent, high-value items.

• US data residency only. The Agents API processes in the US; there is no non-US residency option today.
• No ZDR (Zero Data Retention). ZDR is not available for the Agents API.
• Self-hosting the sandbox does not lift these. Running your own sandbox controls the execution environment, not the API’s residency or retention terms.
• Beta. It ships behind OpenAI-Beta: agents=v1; treat it as beta in production planning.
• Billing. Model API rates + standard tool rates + container rates for hosted sandboxes.

If the requirement is EU-only residency or ZDR:
    Agents API is NOT eligible (even self-hosted sandbox).
    → Use Agents SDK (you run it, your residency/retention) or
      Responses + tools with your own controls.

Decision framework

Use RUNTIME-FIT to choose and secure an agent design.

The decisive early check is residency/ZDR: it can eliminate the Agents API before any other consideration.

Common mistakes

Scenario challenge

Scenario. A European bank wants a durable agent that migrates a large legacy codebase over many hours, running shell commands and reading an internal repo via MCP, with progress dashboards. Data must remain in the EU and the bank’s policy requires zero data retention. An architect proposes the Agents API with a self-hosted sandbox “so the data stays in our EU infrastructure and ZDR is satisfied”.

Expert reasoning trace.

1. Check residency and ZDR first. The bank requires EU residency and ZDR. The Agents API is US-only with no ZDR – that is a hard constraint, checked before anything else.
2. Reject the self-hosted-sandbox reasoning. A self-hosted sandbox controls where execution happens, but the Agents API’s residency and retention terms are properties of the API, not the sandbox. So self-hosting does not make the Agents API EU-resident or ZDR-compliant. The architect’s proposal fails on a factual constraint.
3. The durability need is real, but it must be met another way. The Agents SDK, which the bank runs in its own EU infrastructure, gives durable orchestration under the bank’s own residency and retention controls – the model calls still go to the API, so the bank must also confirm the model endpoint meets its data terms, but the harness is theirs.
4. Keep least privilege. Shell and repo MCP access are powerful; scope the MCP connection to read-only where possible and gate any write/commit behind approval.
5. Add tracing for the multi-hour run so the migration is auditable and recoverable.
6. Consider subagents carefully: parallelising per-module migration is attractive, but in the SDK the bank owns that orchestration and its cost/rate implications.

Exam-correct decision: the Agents API is ineligible because of EU residency and ZDR (self-hosting the sandbox does not change that); build on the Agents SDK in the bank’s own infrastructure with least-privilege MCP, approval gates on writes, and full tracing. Not “Agents API with a self-hosted sandbox satisfies ZDR”.

Assessment traps

Practice questions

Each item states how many responses to select. Commit before revealing.

Key takeaways

• Three runtimes: Responses + tools (you own the loop), Agents SDK (code-first, you run it), Agents API (OpenAI-managed Codex harness).
• Choose by managed durability, custom orchestration and simplicity – and check residency/ZDR first.
• The Agents API is US-only with no ZDR; a self-hosted sandbox controls execution, not those terms.
• Agents act through tools including MCP; grant least privilege to limit blast radius.
• Use multi-agent handoffs for routing and bounded subagents for parallel sub-tasks.
• Gate irreversible actions behind human approvals and add guardrails against injection.
• Always add tracing/observability so agent behaviour is auditable and debuggable.