Working Codex as a Headless Agent

interactively in a terminal or an IDE.

That is helpful. Nevertheless it additionally results in a pure query:

Can Codex change into a callable a part of our personal workflow?

Let’s reply that on this submit.

Particularly, we’ll discover tips on how to run Codex as a headless agent inside a small automation workflow, and illustrate the concept with a concrete case research.

1. The Workflow Form We Need

We will consider Codex as a really succesful agent.

Once we use Codex interactively, it lives inside a dialog. You might want to be there the entire time to evaluate and steer it towards what you really need.

A headless workflow doesn’t require that. There, Codex stops being a dialog associate and turns into only one callable step in a bigger course of.

At a excessive degree, we are able to consider the workflow like this:

The trick is conserving that step bounded: the workflow provides the duty context for Codex, and Codex returns an output that the subsequent step can simply eat.

This sample is beneficial when the general course of is repeatable, however one step requires agentic work. For instance, a scheduled job may have to arrange a weekly analysis digest, or a CI workflow might must run an automatic evaluate.

By bringing Codex into a bigger workflow, we get the advantages of either side: strange code retains the method deterministic, structured, and simple to examine, whereas Codex handles the open-ended components that may genuinely profit from an agent.

That is the workflow form we’ll construct within the case research.

2. Case Examine: Constructing a Analysis Digest Workflow

Right here, we construct a small automation workflow that asks Codex to analysis latest developments on a subject and turns the consequence into an HTML digest.

In code, our workflow seems like this in Python:

run = prepare_research_task()

temporary = run_codex(run)

html_path = render_digest(temporary)

The division of labor may be very easy. Python prepares the duty and produces the ultimate artifact. The open-ended analysis step within the center is dealt with by Codex.

Now let’s unpack the workflow one piece at a time.

2.1 Making ready the Run

In step one, we solely put together the inputs wanted for the Codex run. This implies three issues: the immediate, the output schema, and the file areas for the ultimate abstract and execution hint.

Identical to configuring a normal agent, we have to put together a immediate for Codex to make clear the duty and our anticipated end result.

We begin with the immediate. Identical to configuring a normal agent, we have to inform Codex what the duty is and what our anticipated end result is. We use the next immediate template:

Analysis materials developments in {{TOPIC}} from {{WINDOW_START}} via
{{WINDOW_END}}, inclusive, utilizing dwell internet search.

Return at most {{MAX_EVENTS}} occasions.

For every occasion, embody:
- date
- title
- class
- abstract
- why it issues
- sources

Return solely the JSON object described by the equipped schema.

Then Python turns this right into a concrete immediate for one run:

from datetime import date, timedelta

def prepare_research_task(
    subject: str,
    as_of: date,
    lookback_days: int,
    max_events: int,
) -> dict:
    window_end = as_of
    window_start = as_of - timedelta(days=lookback_days - 1)

    immediate = (
        PROMPT_TEMPLATE
        .exchange("{{TOPIC}}", subject)
        .exchange("{{WINDOW_START}}", window_start.isoformat())
        .exchange("{{WINDOW_END}}", window_end.isoformat())
        .exchange("{{MAX_EVENTS}}", str(max_events))
    )

    return {
        "immediate": immediate,
        "schema_file": "schemas/evidence_brief.schema.json",
        "brief_file": "outputs/temporary.json",
        "trace_file": "outputs/run.jsonl",
    }

Be aware that as a substitute of asking Codex to return a free-form report, we ask it to return a structured JSON. That is necessary as a result of the subsequent step can eat Codex’s consequence programmatically. Right here is the schema we use:

{
    "subject": "...",
    "window_start": "YYYY-MM-DD",
    "window_end": "YYYY-MM-DD",
    "abstract": "...",
    "occasions": [
        {
            "date": "YYYY-MM-DD",
            "title": "...",
            "category": "...",
            "summary": "...",
            "why_it_matters": "...",
            "sources": [
                {
                    "publisher": "...",
                    "title": "...",
                    "published_date": "YYYY-MM-DD",
                    "url": "https://..."
                }
            ]
        }
    ]
}

Additionally, we use brief_file to retailer the ultimate structured reply, and trace_file to retailer the execution hint from the headless run. These paths shall be used once we name Codex within the subsequent step.

At this level, nothing agentic has occurred but. We solely did the required preparation work.

2.2 Working Codex Headlessly

First issues first, ensure that the Codex CLI is offered from the command line. If you have already got Node.js and npm put in, you are able to do this:

npm set up --global @openai/codex

Then sign up and test the set up:

codex login
codex login standing
codex --version

To run Codex non-interactively, we want codex exec. The core command seems like this:

codex --search exec 
  --model gpt-5.6-sol 
  --json 
  --output-schema schemas/evidence_brief.schema.json 
  -o outputs/temporary.json 
  -

Some explanations on the arguments:

• --search: permits Codex to make use of dwell internet search.
• --model: which mannequin to make use of for the run.
• --output-schema: tells Codex the anticipated output form.
• -o: tells Codex to jot down the ultimate reply to temporary.json.
• --json: makes Codex emit JSONL occasions to stdout, which we write to run.jsonl (the hint file).
• -: tells Codex to learn the immediate from stdin.

Codex CLI additionally helps execution controls which might be helpful in automated environments. For instance, we now have the --sandbox argument, similar to --sandbox read-only (limits the run to read-only entry) and --sandbox workspace-write (permits adjustments contained in the workspace). These settings are helpful when the agent might examine or modify native information.

In Python, we are able to use subprocess.run() to name the identical command:

import json
import subprocess
from pathlib import Path

def run_codex(run: dict) -> dict:
    command = [
        "codex",
        "--search",
        "exec",
        "--model",
        "gpt-5.6-sol",
        "--json",
        "--output-schema",
        run["schema_file"],
        "-o",
        run["brief_file"],
        "-",
    ]

    Path(run["brief_file"]).dad or mum.mkdir(
        dad and mom=True,
        exist_ok=True,
    )

    with open(run["trace_file"], "w", encoding="utf-8") as hint:
        subprocess.run(
            command,
            enter=run["prompt"],
            textual content=True,
            stdout=hint,
            test=True,
        )

    return json.masses(
        Path(run["brief_file"]).read_text(encoding="utf-8")
    )

2.3 Rendering the Digest As HTML

At this closing step, we flip the structured temporary produced by Codex into HTML:

from pathlib import Path

def render_digest(
    temporary: dict,
    output_file: str = "outputs/digest.html",
) -> Path:
    html = f"""
    
      
        
        
{temporary["summary"]}

        {"".be a part of(
            f"
{occasion['title']}
"
            f"
{occasion['summary']}
"
            for occasion briefly["events"]
        )}
      
    
    """

    output_path = Path(output_file)
    output_path.write_text(html, encoding="utf-8")

    return output_path

The renderer above receives a traditional Python dictionary and writes an HTML file.

That concludes our three-step workflow.

2.4 Working the Workflow

Now let’s run the workflow on a concrete subject.

Right here, I take advantage of AI data-center infrastructure because the analysis subject. There’s fairly a little bit of growth happening lately. I need to use Codex to assist me see the traits.

run = prepare_research_task(
    subject="AI data-center infrastructure",
    as_of=date(2026, 7, 12),
    lookback_days=30,
    max_events=6,
)

temporary = run_codex(run)

html_path = render_digest(temporary)

Codex carried out the deep analysis and generated a structured dictionary in temporary, after which render_digest() turns the structured temporary into an HTML web page at outputs/digest.html.

The HTML digest comprises the abstract, a timeline, occasion playing cards, and supply hyperlinks. That is the ultimate output of the workflow.

As a result of we use --json, Codex writes the occasion stream to stdout, which we saved to run["trace_file"]. The hint consists of occasions, which could be when the run begins, or when Codex performs internet searches, or when intermediate messages are produced. That is helpful for inspecting and debugging headless runs.

3. When This Sample Is Helpful

In lots of workflows, some steps carry out deterministic processing, whereas others remedy open-ended questions. By placing an agent inside a workflow orchestrated by the deterministic code, we get each adaptability and management.

However right here, we aren’t constructing a customized agent from scratch. We’re utilizing Codex, which already provides us a succesful agentic atmosphere, instrument use functionality, sandboxing, and many others.

With codex exec, we are able to entry these capabilities immediately from a script.

Codex can nonetheless be used interactively, in fact. However headless execution provides it one other position, that’s, a callable element contained in the workflows we already use.

Give it a attempt!