Build a coding agent with GPT 5.1

Author: Katia Gil Guzman (OpenAI)
Published: 2025-11-13
Source: OpenAI Cookbook

Executive Summary & Architecture

This reference implementation details the architecture of an autonomous coding agent built on the OpenAI Agents SDK and the Responses API. The agent can scaffold brand-new applications from user prompts, iterate on codebases through patches, execute terminal build/test commands, and retrieve fresh documentation.

Core Tool Harness Configuration

apply_patch: Structured file editing tool applying unified diffs to project files.
shell (LocalShellCall / ShellExecutor): Executes shell commands in an isolated directory with timeout enforcement and explicit human approval gates.
web_search (ResponseFunctionWebSearch): Retrieves up-to-date documentation and package information.
Context7 MCP: Model Context Protocol integration providing indexed library documentation.

Reference Shell Executor with Safety & Approval Gates

class ShellExecutor:
    """
    Shell executor for coding agent harness.
    - Runs all commands inside isolated `workspace_dir`
    - Captures stdout/stderr
    - Enforces timeout from `action.timeout_ms`
    - Enforces mandatory human approval gate before command execution
    """
    def __init__(self, cwd: Path):
        self.cwd = cwd

    async def __call__(self, request: ShellCommandRequest) -> ShellResult:
        action = request.data.action
        await require_approval(action.commands)
        # executes in isolated subprocess with timeout handling

Decision Rules & Loop Controls

When configuring shell execution tools for coding agents, do enforce strict workspace directory isolation and human approval gates, because arbitrary command execution in un-sandboxed environments creates critical security and system destruction risks.
When executing multi-step agent workflows, do implement an outer controller loop to handle MaxTurnsExceeded and dependency errors, because agents can exhaust turn limits or enter error loops without harness-level retries.
When editing multi-file codebases, do use structured patching tools (apply_patch) rather than whole-file rewrites, because structured diffs minimize token consumption and reduce unintentional code clobbering.

What the Source Does NOT Claim

Does NOT claim that un-sandboxed shell command execution is safe for autonomous agents.
Does NOT claim that single-pass generation can reliably build complex applications without outer feedback loops.