Building One Agent from Coordinated Roles in Codex

Codex calls a conversation an agent. That is a useful product label, but it is not enough for a role that other people or agents need to rely on.

For that job, I want a role with a clear purpose, an interface, the right project context, a current task identity, and a way to return work after the original caller has moved on. I also want to be able to change or rebuild it without treating one old chat as the only record of how it works.

This is a practical blueprint, not a click-by-click installation guide. It shows the smallest useful shape for building one public agent from coordinated roles in Codex. The broader model is in A Practical Architecture for Reliable Multi-Agent Systems.

Start with one owner and fresh workers

The simplest useful operating shape is smaller than many multi-agent diagrams suggest.

public entry point
  -> domain owner
      -> fresh worker when substantial work is needed
      -> private specialist when recurring focused context earns it
  -> owner-approved result returns to the requester

The domain owner is the standing role. It understands what the domain owns, chooses the work, integrates what comes back, and stands behind the result. In the original system, this role was called the Conductor; the name is less important than the responsibility.

A fresh worker is usually the right choice for repository work, a deep investigation, parallel execution, or a task that benefits from a clean context. Add a standing specialist only when the same focused context keeps returning and the cost of rebuilding it is real.

This is the design decision behind When an Agent Needs to Be a Service, Not a Chat. Do not make planner, implementer, tester, and reviewer permanent roles merely because a development team has those job titles. They can begin as fresh worker shapes and become standing services only when the work proves they should.

Give the domain two working spaces

One folder can hide two different jobs.

The manager project develops the agent over time. It holds the domain charter, evaluations, development plans, and decisions about skills, workflows, and internal topology.

The operating project gives the live owner and its workers the current instructions, source guides, runbooks, and work area for the domain’s actual job.

Here is a compact proposed layout:

customer-intelligence/
  manager/
    AGENTS.md
    DOMAIN-CHARTER.md
    evaluations/
    development-plan.md

  operating/
    AGENTS.md
    SERVICE-INTERFACE.md
    source-guides/
    runbooks/
    runtime-endpoints/
      owner/
        AGENTS.md
        role.md
        bootstrap.md

This is a Codex implementation pattern, not a claim that every system needs these exact folders. The important separation is that a management context assesses and improves the agent, while the operating context performs today’s work. A manager can make a small decision directly, but it should not quietly become the system’s long-running worker queue.

How to Layer AGENTS.md for Real Agent Work explains how the instruction files in this layout work together.

Define the service before creating the task

Before creating a persistent task, write the short files that give it an operating identity.

An interface should give a caller an honest request: objective, source pointer, limits, close condition, return destination, and a stable identity for an accidental retry. The focused instruction is not the same thing as the larger evidence bundle. One tells the role what to do now; the other tells it where to inspect the work.

That distinction prevents a common failure: giving a task a large packet of material as though it were its current instruction. The role gets neither a clear job nor a compact record of the request.

Create, read back, and activate in stages

Once the source definition is ready, create the task in the intended saved project and working directory. Then read back the facts that matter: the task identity, project association, working directory, model profile, and interface version.

Do not infer those facts from the bootstrap prompt. A good prompt does not prove where the task was created or what context it actually received.

If you maintain a live endpoint registry, add the new task as inactive first. Validate its configuration and route before normal requests depend on it. Then activate it only after the checks pass.

The sequence is deliberately modest:

source definition
  -> task created in the right project
  -> live identity read back
  -> inactive registration checked
  -> route and return tested
  -> normal work admitted

Each step makes a different claim. A source definition is not a running task. A running task is not a tested route. A tested route is not evidence that a real requester received useful work.

The Proof Ladder for AI Systems owns the full evidence model. How to Change an Agent System Without Breaking Live Work applies it when a role is being replaced.

Keep the route simple and explicit

The public agent should feel like one agent to a caller. Internally, the request can move through several responsibilities.

request runtime
  -> public entry point
  -> domain owner
  -> private specialist or fresh worker
  -> domain owner accepts and integrates the return
  -> public entry point returns the owner-approved result
  -> requester delivery

The public entry point is a known front door. It validates an admitted route and returns the owner-approved result. The owner interprets the request and decides which help to use. A specialist or worker returns to the owner that needs to make the next decision.

The request runtime handles deterministic mechanics such as compact tickets, duplicate controls, callbacks, and recovery records. A separate lifecycle tracker can keep open obligations and update points visible. Neither component decides whether the domain result is good enough.

That is the practical split behind the architecture: software keeps the request path and record trustworthy; the owner makes the domain judgment. Transport Is Not Ownership explains why that separation matters, and Done Is Not Delivered covers the final return to the requester.

Put state where it can do its job

Do not ask the task conversation to remember the whole system.

Keep role definitions, interfaces, model profiles, and rebuild instructions in source control. Keep live task bindings, compact requests, callbacks, and locks in the Runtime. Keep substantial evidence and working artifacts in the domain work area. Keep reusable lessons in a maintained knowledge system.

That separation makes a clean replacement possible without copying old task history into a new role. It also keeps a small request record from turning into an archive of source material and transcripts.

Where an Agent System Keeps Its State is the canonical guide to those boundaries.

Grow the topology only when the work proves it

After the smallest design is working, a domain may earn more standing roles. A development agent, for example, may eventually keep a planner, implementer, tester, or reviewer because each carries recurring, costly context that the owner needs often.

That is an expanded topology, not a starting requirement. The manager project should review whether each role improves the work enough to justify its instructions, task context, model cost, monitoring, and recovery burden.

Model choice follows the same rule. A public entry point can use a faster profile because its job is narrow. The domain owner needs enough reasoning for decomposition and integration. A specialist or worker gets the model and effort the actual task needs. One default profile for everything is convenient, but it can make the fast path slow and the difficult path weak.

Build the smallest thing you can verify

The goal is not to recreate a large internal organization in Codex.

Start with one owner, a clear project context, a fresh worker for larger tasks, a route that returns work to the owner, and a visible way to get the approved answer back to the requester. Add a public entry point when a stable address solves a real problem. Add specialists when their context earns the cost.

That is how a collection of capable chats becomes one agent people can actually rely on: not through more names, but through a small set of roles with clear jobs, current context, explicit return paths, and evidence that the system works.