Chapter 1: Production Agent Architecture with the OpenAI Agents SDK
What You Will Learn
Map the requirements of the Incident triage agent platform for a SaaS operations team onto a three-layer architecture of harness, sandbox, and state
Identify the trust boundary between harness and sandbox and articulate why credential isolation matters in production
Explain why sandboxed execution requires a different architectural approach than traditional function-calling agents
Distinguish between conversation state, workspace state, and audit state and describe where each belongs
Reason about production agent architecture without relying on specific SDK imports or implementation details
Prerequisites
No additional prerequisites beyond those listed in About This Book.
Concept Overview
The Incident triage agent platform for a SaaS operations team receives alerts from monitoring systems, assembles a per-Incident investigation workspace, and produces operator-facing triage summaries. Each summary contains severity, likely cause, affected services, supporting evidence, and recommended next actions. The platform uses the OpenAI Agents SDK to run sandboxed agents that inspect logs, metrics exports, deployment diffs, and runbook content. Model-generated code executes inside isolated environments.
Production agent architecture on this SDK rests on three distinct layers that separate reasoning, execution, and durability. The harness contains the model, the tool-calling loop, memory, and tracing. It runs inside your process and holds all sensitive credentials. The sandbox layer hosts the compute environment where filesystem operations and code execution actually occur. It is untrusted by design. Treat it as hostile. The state layer externalizes durability across conversation history, workspace snapshots, and audit records. Neither harness restarts nor sandbox container failures destroy operational context.
Traditional function-calling agents typically execute tools inside the harness process, sharing memory and credentials with the model loop. Sandbox agents sever that connection. The model can write and execute arbitrary code inside the sandbox. That power demands isolation. Credentials belong in the harness, never in the sandbox. I once saw a model-generated shell script dump every environment variable to stdout because the harness had passed the OpenAI API key into the sandbox container.
State separation follows the same boundary. Conversation state belongs to the harness during a run; it tracks operator dialogue and agent reasoning history, and it is persisted to the external state layer for continuity across restarts. Workspace state belongs to the sandbox while active; it includes mounted log bundles, cloned repositories, and command outputs. Durable workspace references and snapshots live in the state layer for rehydration. Audit state belongs to persistent storage outside both; it captures Incident records, triage reports, agent run records, and execution traces. Collapsing these categories into a single store creates recovery hazards and compliance gaps.
Step-by-Step Implementation
Because this chapter establishes the governing conceptual framework, the steps below are architectural design decisions rather than runnable code.
Step 1: Model the Incident Triage Domain
An alert arrives from a monitoring source such as PagerDuty. The platform normalizes it into an Incident entity with an identifier, title, status, severity, timestamp, and owning service. The raw alert payload becomes an AlertEvent. The platform looks up the affected service in a ServiceCatalogEntry to find the team, repository URL, and runbook URL. For severe incidents, the platform may also produce a RemediationPlan with ordered steps, risk level, approval requirements, and rollback notes.
These entities form the system's boundaries. The input boundary is the alert stream and service catalog metadata. The output boundary is the TriageReport, which contains a summary, confidence score, suspected root cause, evidence items, and recommended actions. Between input and output sits the InvestigationWorkspace, which declares the manifest of artifacts the agents will inspect.
Step 2: Design the Harness Layer
The harness is the trusted reasoning core. It receives the normalized alert, maintains operator conversation continuity, and decides which subagents to invoke. It holds the OpenAI API key, any downstream LLM provider tokens, and business credentials for internal APIs. The harness never forwards these secrets into the sandbox.
The harness orchestrates subagents through handoffs and agents-as-tools patterns. One subagent classifies severity. Another inspects telemetry logs. A third proposes remediation steps. The harness routes work to them, but it does not execute their code. Function-calling agents are not sandboxed agents. The harness only reasons and delegates.
from typing import Protocol
class HarnessRouter(Protocol):
"""Conceptual interface for the trusted harness layer."""
def route_to_classifier(self, incident_id: str) -> str: ...
def route_to_log_analyst(self, incident_id: str) -> str: ...
def route_to_planner(self, incident_id: str) -> str: ...
This protocol illustrates the harness role. It decides where to send an Incident, but it does not perform the inspection itself. The actual SDK implements this routing through Runner and agent handoffs, which later chapters cover in detail.
Step 3: Isolate the Sandbox Layer
Each subagent runs inside its own sandbox environment. The InvestigationWorkspace declares a manifest that mounts logs, repository state, and runbook artifacts into the sandbox filesystem at startup. The model inside the sandbox inspects these files, executes commands, and may apply patches to runbook documents.
The sandbox client determines the isolation level. UnixLocalSandboxClient offers no real isolation. Use it only for development. DockerSandboxClient provides containerized isolation and is the minimum production baseline. Hosted sandbox clients add managed lifecycle and IAM-scoped credential separation. The sandbox is treated as potentially hostile. The model generates every command that runs there.
Never trust model-generated code.
Step 4: Externalize the State Layer
Operator conversation history survives harness restarts through Redis-backed session storage that preserves dialogue and reasoning state. Workspace snapshots survive container expiration through object storage. Incident records, triage reports, and agent run records persist in PostgreSQL for audit and resume. Execution traces feed into the tracing backend for post-mortem analysis and compliance review.
This separation enables failure recovery. If a sandbox container expires during a long log analysis, the harness can rehydrate the workspace snapshot into a fresh container and resume. If the harness process restarts, the operator conversation continues from the session store. If auditors request evidence, the PostgreSQL records and traces provide a complete chain.
Step 5: Enforce Trust Boundaries and Guardrails
Input guardrails validate alerts and workspace artifacts before they enter agent reasoning. Output guardrails validate every triage summary and remediation plan before an operator sees the result.
Guardrails are not optional safety nets; they are required security controls.
Credentials remain scoped to the harness process. Sandbox clients use separate IAM roles or Docker secrets. The harness passes only the investigation manifest and user query into the sandbox. It never passes database connection strings, API keys, or internal tokens.
Local sandbox clients have no place in production.
Full Example
The scenario below is a worked architectural walkthrough, not a runnable implementation.
from dataclasses import dataclass
from datetime import datetime
from typing import Any, Dict, List, Optional
@dataclass
class AlertEvent:
source: str
timestamp: datetime
signal_type: str
threshold: float
raw_payload: Dict[str, Any]
@dataclass
class Incident:
incident_id: str
title: str
status: str
severity: str
created_at: datetime
owning_service: str
@dataclass
class ServiceCatalogEntry:
service_name: str
team: str
repo_url: str
runbook_url: str
@dataclass
class InvestigationWorkspace:
manifest_inputs: Dict[str, Any]
mounted_artifacts: List[str]
snapshot_id: Optional[str]
sandbox_provider: str
@dataclass
class TriageReport:
summary: str
confidence: float
suspected_root_cause: str
evidence_items: List[str]
recommended_actions: List[str]
@dataclass
class RemediationPlan:
ordered_steps: List[str]
risk_level: str
approval_required: bool
rollback_notes: str
@dataclass
class AgentRunRecord:
run_id: str
agent_name: str
session_id: str
trace_id: str
duration_ms: int
outcome: str
class UnixLocalSandboxClient:
pass
class DockerSandboxClient:
pass
An operator receives a high-priority page. The monitoring system emits an AlertEvent with threshold breaches and a raw payload. The harness ingests the alert, creates an Incident record in PostgreSQL, and looks up the ServiceCatalogEntry for the affected service.
The harness constructs an InvestigationWorkspace manifest. The manifest mounts the last hour of application logs from object storage, clones the service repository at the current deployment ref, and pulls the latest runbook document. The harness selects a classifier subagent and routes the Incident to a sandbox configured for fast, inexpensive inference. The classifier returns a severity of critical and flags the deployment diff as the likely culprit.
Next, a log analyst subagent receives the handoff in its own sandbox. The analyst inspects the mounted logs, runs aggregation commands, and extracts error spikes correlated with the deployment timestamp. The harness then hands off to a remediation planner subagent in a third sandbox. The planner reads the runbook, proposes a rollback procedure, and uses the sandbox filesystem tools to generate a minimal patch for the runbook update.
Finally, the harness aggregates partial results into a TriageReport. Output guardrails verify that the recommended rollback does not skip required approvals and that the evidence items reference actual log lines. The harness persists the report to PostgreSQL, writes an AgentRunRecord with duration and outcome, and surfaces the summary to the operator. The entire execution graph is captured in the trace store.
The architecture diagram illustrates a single Incident lifecycle. The harness remains the sole trusted component. It doesn't share credentials with any sandbox. Each subagent operates in its own sandbox with no cross-container access. State stores provide durability and auditability independent of the compute layer. This pattern repeats for every alert the platform processes.
Common Mistakes
Treating the sandbox as an extension of the harness process. The sandbox runs model-generated code. Treat it as untrusted compute. Keep all harness credentials out.
Passing harness API keys into sandbox environment variables. This violates the trust boundary. Use provider-specific IAM scopes or Docker secrets scoped to the sandbox client instead.
Storing workspace artifacts in harness process memory. Log files, repository clones, and command outputs belong in the sandbox filesystem. Use manifest entries to mount them and let the sandbox provider manage the lifecycle.
Conflating conversation history with workspace state. Operator chat history is harness conversation state. File contents and command outputs are sandbox workspace state. Mixing the two complicates recovery and produces incomplete audit trails.
Porting function-calling agent patterns directly without redesigning the trust boundary. Traditional agents execute tools inside the harness process. Sandbox agents require explicit isolation between reasoning and execution. Redesign the boundary before migrating logic.
Performance and Production Considerations
Harness memory scales with conversation context and active routing tables, not sandbox compute. Keep the harness lean; offload heavy file operations to the sandbox.
Sandbox cold-start latency ranges from sub-50 milliseconds for local development clients to 200 milliseconds or more for hosted providers. Incident response SLAs must account for container provisioning time.
Provider concurrency limits cap parallel subagent fan-out. Budget container slots across classifier, log analyst, and remediation planner runs.
Externalized state adds network round trips, but it enables horizontal scaling and failure recovery. Do not trade durability for latency in the state layer.
Agent traces and audit records grow quickly. Set retention policies on PostgreSQL run record tables and tracing backend storage before production launch.
Token usage increases with tool-call round-trips. Plan for significantly higher LLM spend than single-shot completions; the harness loop generates multiple reasoning steps per Incident.
Summary
The Incident triage agent platform for a SaaS operations team demonstrates why production agent architecture requires explicit separation between harness, sandbox, and state. The harness owns reasoning and credentials. The sandbox hosts untrusted model-generated code. The state layer ensures durability and auditability across failures. Sandboxed execution is not a minor configuration change. It is an architectural pivot that affects how you design trust boundaries, route subagents, and persist data. The chapters that follow build on this foundation with concrete SDK implementations, but the conceptual model established here remains the governing framework.
Key Terms
Harness layer: the trusted reasoning core that holds credentials, orchestrates subagents, and maintains conversation state
Sandbox layer: the untrusted compute environment where model-generated code executes and workspace artifacts reside
State layer: externalized durable storage for sessions, workspace snapshots, and audit records
Trust boundary: the explicit separation between harness and sandbox where credentials must never cross
InvestigationWorkspace: the per-Incident manifest that declares which artifacts enter the sandbox for analysis
Manifest: the declarative specification of files, repositories, and mounts provided to a sandbox at startup
Subagent: an agent delegated to perform a specialized task, such as classification or log analysis
Handoff: an orchestration pattern where the harness routes control from one agent to another
Agent-as-tool: an orchestration pattern where a parent agent invokes another agent as a callable capability
Conversation state: operator dialogue and agent reasoning history owned by the harness
Workspace state: files, command outputs, and mounted artifacts owned by the sandbox
Audit state: Incident records, triage reports, and execution traces persisted for compliance and review
Input guardrails: validation controls applied to alerts and artifacts before they enter agent reasoning
Output guardrails: validation controls applied to triage summaries and remediation plans before operator presentation
Sandbox client: the runtime implementation that hosts the sandbox environment, such as Docker or a hosted provider
Credential isolation: the practice of keeping harness secrets out of sandbox environments through IAM scopes or mount controls
RemediationPlan: the ordered set of recovery steps, risk assessment, and rollback guidance produced for an Incident
Mini Quiz
A security audit reveals that sandbox containers in the Incident triage platform have access to the OPENAI_API_KEY environment variable. Which mistake occurred?
A. The state layer was configured to store API keys in Redis
B. The classifier subagent was given excessive conversation history
C. The sandbox client defaulted to UnixLocalSandboxClient
D. The harness violated the trust boundary by passing credentials into the sandbox
According to the three-layer model, where does operator conversation history conceptually belong?
A. Sandbox layer, because it includes all files the model touches
B. State layer, because it persists across restarts
C. Harness layer, because it tracks dialogue and reasoning history
D. Object storage, because it holds workspace snapshots
A log analyst subagent must inspect a 2GB application log bundle during an Incident investigation. Where should this bundle reside during analysis?
A. In harness process memory for fast access
B. In the Redis session store alongside operator messages
C. In the PostgreSQL audit database as a binary column
D. In the sandbox filesystem, mounted via the InvestigationWorkspace manifest
During a long-running investigation, the sandbox container expires before the log analyst completes its work. Which architectural capability allows the platform to resume?
A. Harness layer re-running the classifier from scratch
B. Input guardrails revalidating the original alert payload
C. Sandbox layer cold-start latency reduction
D. State layer snapshot and rehydration of workspace state
Why is adopting sandboxed execution described as an architectural pivot rather than a simple configuration change?
A. It requires replacing PostgreSQL with a vector database
B. It reduces LLM token usage by combining reasoning and execution
C. It eliminates the need for output guardrails on triage reports
D. It changes trust boundaries, subagent routing, and data persistence design
Answers are provided in the Answer Key at the end of the book.
Activity
List every entity from the Incident triage platform domain: Incident, AlertEvent, ServiceCatalogEntry, InvestigationWorkspace, TriageReport, AgentRunRecord, and RemediationPlan.
Map each entity to exactly one of the three architectural layers (harness, sandbox, or state) based on where it is created, owned, and durably stored during an investigation.
For each entity, identify any fields that could represent credentials, secrets, or configuration that must remain harness-resident. Document why those fields must never be serialized into the sandbox environment.
Draft a one-page trust-boundary specification for the platform that lists which data types and artifacts are permitted to cross from harness to sandbox, from sandbox to state, and which are explicitly blocked at the harness-to-sandbox boundary.
Include RemediationPlan in your layer mapping and justify whether its ordered steps, risk level, and approval flags belong to harness reasoning, sandbox execution, or state persistence.
On April 15, 2026 the OpenAI Agents SDK shipped a new architecture: native sandbox execution, a model-native harness, subagent fan-out across isolated containers, and code mode with apply_patch. This book is built on those APIs from chapter one and treats the sandbox as the trust boundary that production agents need.
You build a real production system end to end: an Incident triage agent platform for a SaaS operations team that classifies alerts, inspects logs in parallel sandboxes, applies minimal runbook patches, and produces operator-facing recommendations under guardrails. The same application runs through all 11 chapters, so every new pattern lands on a working system instead of a toy snippet.
What you build: - A three-layer architecture that separates harness, sandbox, and externalized state with the trust boundary drawn explicitly
- A hardened DockerSandboxClient with mount allowlists, blocked credential patterns, and a leak audit that fails fast before any container starts
- SandboxAgent plus Manifest with GitRepo entries, code mode for log aggregation inside the sandbox, and apply_patch for minimal runbook edits
- agents.Session for operator continuity (OpenAIConversationsSession for dev, RedisSession in production) and tracing that joins runs across multi-turn investigations
- Three subagents (classifier, log analyst, remediation planner) composed through Handoffs and agents-as-tools, each routed to a cost-optimal model via a shared LitellmProvider
- Parallel sandbox fan-out with asyncio.gather, per-subagent timeouts, and degraded-report aggregation when a sandbox fails
- Composite manifests with patch-delta tracking for snapshot and rehydration after container expiration
- Mandatory input and output guardrails with parametrized pytest, FakeSandboxFactory for fast harness tests, and Docker integration tests
- Production deployment with concurrency governors, cost budgets enforced before delivery, and a pre-flight health check that audits the trust boundary on every run
- A migration framework that audits legacy function-calling agents for credential and filesystem leaks and ports the survivors onto the sandbox boundary
What makes this book different: - Built on the new SDK surface. Every code sample uses agents.sandbox, SandboxAgent, Manifest, SandboxRunConfig, and function_tool from openai-agents 0.14.x. API call shapes were checked against the imported module so the code runs as written.
- Honest about isolation. UnixLocalSandboxClient is called what it is: a development client with no isolation. Production examples default to DockerSandboxClient or hosted providers, and the trust boundary is non-negotiable.
- Real sandbox providers. Side-by-side coverage of Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel with cold-start, egress controls, IAM scoping, and concurrency caps documented per provider.
- Real package names and pins. openai-agents on PyPI, the seven sandbox provider extras, the litellm extra for provider-agnostic routing, and a 0.14.x line pin that survives the SDK's rapid patch cadence.
Covers the openai-agents Python SDK 0.14.x line, including Sandbox Agents, the model-native harness, subagent orchestration, code mode, apply_patch, externalized state with snapshotting and rehydration, and provider-agnostic LLM routing via LiteLLM. The TypeScript port lives in a separate repo and is out of scope.
Prerequisites: Intermediate Python (3.10 or newer). Familiarity with at least one agent framework (OpenAI function calling, LangGraph, Microsoft Agent Framework, Google ADK, CrewAI, or PydanticAI). Basic Docker reading ability for the local sandbox chapters. No prior sandbox or container expertise required.
Production agents need real workspaces, real isolation, and real state. Build them the way the SDK was redesigned to support.
Release DateApril 29, 2026
GenreSoftware & AI Development
ISBN979-8-90377-037-3
Read and listen on the go with the unQbd app.Get the app