OpenAI's Codex agent loop deep dive
This OpenAI post is a useful technical read because it explains the agent loop, context construction, model calls, and tool orchestration behind Codex.
A coding agent is mostly its harness. The model matters, but how context is prepared, tools are defined, permissions are enforced, and results are fed back determines whether the agent produces useful code or expensive noise.
Source
Unrolling the Codex agent loop
By: OpenAI (Michael Bolin)
Type: Engineering article
This article goes below the product surface of Codex CLI and explains the loop that orchestrates everything. For anyone building or understanding coding agents, the harness design is more instructive than the model choice.
How the Codex agent loop actually works
Codex is a suite of software agent offerings — CLI, Cloud, and VS Code extension. They all share the same core harness that drives the agent loop: prepare a prompt, call the model, execute tool calls, feed results back, and repeat until the model produces a final message instead of another tool call.
The loop starts with building the initial prompt. The Responses API takes a JSON payload with three key fields: instructions (system/developer message), tools (what the model can call), and input (the conversation content). Each field is assembled from multiple sources in a specific priority order.
Instructions come from a model-specific prompt file bundled into the CLI (like gpt-5.2-codex_prompt.md) or a custom model_instructions_file in the user’s config. Tools include Codex’s built-in shell tool for spawning local processes, a plan tool for task tracking, web search from the Responses API, and any MCP server tools the user has configured. The input list is built in this order: a developer message describing the sandbox and permissions, optional developer instructions from config, optional user instructions aggregated from AGENTS.md files (walking from the git root to the current directory), environment context (cwd and shell), and finally the actual user message.
The ordering matters. More specific instructions appear later in the input list, and the Responses API server controls the final prompt arrangement — system message first, then tools, then instructions, then the input items. The client controls what goes into each slot, but the server decides the ordering of the first three. This separation means the same harness works across different API endpoints.
The Responses API endpoint is configurable. This is a key design decision. Codex CLI works with ChatGPT’s backend, OpenAI’s API, local models through Ollama or LM Studio (via --oss), and cloud providers like Azure — any endpoint implementing the Responses API. The loop isn’t locked to one provider.
Model inference happens via HTTP POST with an Authorization header. The server replies with a Server-Sent Events stream. Each event carries a type: reasoning summaries (response.reasoning_summary_text.delta), output text (response.output_text.delta), function calls (response.output_item.added), and completion signals (response.completed). Codex consumes these events and either streams them to the UI or transforms them into objects appended to the input for the next API call.
After each inference call, the model either produces a final assistant message (terminating the turn) or requests one or more tool calls. For tool calls, Codex executes them in its sandboxed environment — file permissions, network access, and writable folders are all specified in the sandbox description embedded in the prompt. The tool output gets appended to the conversation, and the model is queried again with the full updated context.
As the conversation grows, so does the prompt length. Every model has a context window that includes both input and output tokens. An agent making hundreds of tool calls in one turn can exhaust it. Context window management is therefore one of the harness’s core responsibilities — deciding what to keep, what to summarise, and what to drop as the conversation accumulates.
The conversation model is multi-turn: each new user message includes the full conversation history from previous turns (messages and tool calls). This means the model has continuity across turns but at the cost of growing prompt size.
The practical lesson from the architecture is that each component — instructions sourcing, tool definition, input assembly, sandbox enforcement, event streaming, and context management — is explicit, configurable code. None of it is hidden behind a single “call the AI” function. That transparency is what makes the harness testable and portable.
My take
What stands out is the explicit layering of context. Most agent tutorials show model.call(prompt) as if the prompt is one string. Codex’s reality is four developer messages, aggregated AGENTS.md files from the directory tree, environment context, skills metadata, tool definitions, and sandbox permissions — all assembled in a priority order before the user’s message even appears. The quality of the agent’s output depends on how well that context stack is built, not just on how smart the model is. The configurable endpoint is equally important: it means the harness is a product independent of the model provider. The same loop, tools, and context construction work whether you’re calling GPT-5.2 remotely or running gpt-oss locally through Ollama.
Where this is useful
- When building any coding agent or CLI — the Codex architecture is a reference implementation for how to structure the loop, context assembly, and tool orchestration as explicit, testable code.
- When debugging why an agent produces bad output — the answer is almost always in context preparation (wrong instructions priority, missing AGENTS.md, incomplete environment context), not model quality.
- When deciding whether to lock your agent to one model provider — the configurable endpoint pattern shows how to keep the harness portable.
Apply this: If your agent loop is a single function that builds a prompt string and calls the model, refactor it into the explicit layers Codex uses: instructions sourcing, tool definition, sandbox description, user context aggregation, and then the user message. Each layer becomes independently testable.
What I want to remember
Remember: If I build a coding agent, the loop should be a first-class product. Prompt assembly, tool definitions, sandbox permissions, context management, and event streaming should all be explicit, configurable code — not hidden inside a single model call.