Working Codex as a Headless Agent

interactively in a terminal or an IDE.

That is helpful. However 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 find out how to run Codex as a headless agent inside a small automation workflow, and illustrate the thought with a concrete case examine.

1. The Workflow Form We Need

We are able to consider Codex as a really succesful agent.

After we use Codex interactively, it lives inside a dialog. You should be there the entire time to assessment and steer it towards what you truly 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 stage, we are able to consider the workflow like this:

The trick is preserving that step bounded: the workflow provides the duty context for Codex, and Codex returns an output that the following step can simply devour.

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 organize a weekly analysis digest, or a CI workflow might must run an automatic assessment.

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

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

2. Case Research: Constructing a Analysis Digest Workflow

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

In code, our workflow seems to be like this in Python:

run = prepare_research_task()

transient = run_codex(run)

html_path = render_digest(transient)

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 places for the ultimate abstract and execution hint.

Identical to configuring a typical 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 typical 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}} by
{{WINDOW_END}}, inclusive, utilizing stay 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(
    matter: 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
        .substitute("{{TOPIC}}", matter)
        .substitute("{{WINDOW_START}}", window_start.isoformat())
        .substitute("{{WINDOW_END}}", window_end.isoformat())
        .substitute("{{MAX_EVENTS}}", str(max_events))
    )

    return {
        "immediate": immediate,
        "schema_file": "schemas/evidence_brief.schema.json",
        "brief_file": "outputs/transient.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 following step can devour Codex’s consequence programmatically. Right here is the schema we use:

{
    "matter": "...",
    "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 will likely be used after we name Codex within the subsequent step.

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

2.2 Working Codex Headlessly

First issues first, be sure the Codex CLI is on the market 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 register and verify the set up:

codex login
codex login standing
codex --version

To run Codex non-interactively, we’d like codex exec. The core command seems to be like this:

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

Some explanations on the arguments:

• --search: permits Codex to make use of stay internet search.
• --model: which mannequin to make use of for the run.
• --output-schema: tells Codex the anticipated output form.
• -o: tells Codex to put in writing the ultimate reply to transient.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 can be helpful in automated environments. For instance, we now have the --sandbox argument, equivalent 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"]).father or mother.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,
            verify=True,
        )

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

2.3 Rendering the Digest As HTML

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

from pathlib import Path

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

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

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

    return output_path

The renderer above receives a standard 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 matter.

Right here, I exploit AI data-center infrastructure because the analysis matter. There may be fairly a little bit of improvement happening lately. I wish to use Codex to assist me see the tendencies.

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

transient = run_codex(run)

html_path = render_digest(transient)

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

The HTML digest incorporates 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’re not constructing a customized agent from scratch. We’re utilizing Codex, which already provides us a succesful agentic atmosphere, software use functionality, sandboxing, and so forth.

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

Codex can nonetheless be used interactively, after all. However headless execution provides it one other function, that’s, a callable part contained in the workflows we already use.

Give it a strive!