airflow.providers.common.ai.tools.openai_codex

Give Airflow tools to an agent loop run by the OpenAI Codex SDK.

Note

Experimental; see Stable and experimental features.

Classes

AirflowTools

Airflow's tools for an agent loop run by the OpenAI Codex SDK.

Module Contents

class airflow.providers.common.ai.tools.openai_codex.AirflowTools(*sources, server_name='airflow', tool_timeout=_DEFAULT_TOOL_TIMEOUT_SEC)[source]

Airflow’s tools for an agent loop run by the OpenAI Codex SDK.

Pass toolsets that implement ToolProvider, such as SQLToolset and HookToolset, optionally wrapped with .filtered(), .prefixed() or .renamed() (a .filtered() function runs once, when this is built, with ctx.deps set to None), or individual AirflowTool objects. Codex has no in-process tools, so serve() starts an MCP server on 127.0.0.1 in the running event loop and points a codex app-server child process at it. Start a thread with build_thread_options() and drive its turn with run():

from openai_codex import AsyncCodex

from airflow.providers.common.ai.tools.openai_codex import AirflowTools
from airflow.providers.common.ai.toolsets.sql import SQLToolset

tools = AirflowTools(SQLToolset(db_conn_id="warehouse", allowed_tables=["orders"]))
async with tools.serve() as config, AsyncCodex(config) as codex:
    await codex.login_api_key(api_key)
    thread = await codex.thread_start(**tools.build_thread_options())
    result = await tools.run(await thread.turn("..."))

Each tool keeps the source tool’s name, description and argument schema, and every result passes through Airflow’s secret masker first. A failure the model can correct, such as a query naming a missing column, reaches it as an isError tool result. A failure the model cannot fix, such as a hook raising, makes run() raise ToolCallError, so the task fails and Airflow retries it.

Only the async client, AsyncCodex, is supported. The MCP server runs in the same event loop as the tools, so a synchronous Codex call that blocks that loop’s thread keeps the server from answering, and the call waits until Codex gives up on the tool.

An instance runs one turn at a time and serves one serve() block at a time: build a new AirflowTools per task. A tool call that arrives after a run has ended is refused until the next run() starts. A call that lands after the next run has started cannot be told apart and is served by that run.

Parameters:
  • sources (airflow.providers.common.ai.tools.ToolSource) – Toolsets and tools to serve, in order.

  • server_name (str) – The MCP server name the tools are served under. Letters, digits, _ and - only, as it becomes part of a Codex config key.

  • tool_timeout (float) – Seconds Codex waits for one tool call. What happens to a hook still running when Codex gives up is not verified: the call may be cancelled, or a hook that runs in a thread may run on, and its result is discarded either way.

Raises:

ValueError – when server_name has other characters.

server_name = 'airflow'[source]
tool_timeout = 600.0[source]
async serve()[source]

Serve the tools over MCP for the duration of the block and yield the CodexConfig to use.

Creates an empty CODEX_HOME, an empty working directory and an empty HOME in a temporary directory, starts the MCP server on a free 127.0.0.1 port with a random bearer token, and yields a CodexConfig that points codex app-server at it and applies the safe defaults described in the OpenAI Codex guide. On exit it stops the server and deletes the temporary directory, so leave the block after the AsyncCodex that uses it.

The yielded CodexConfig holds the bearer token in env, so its repr does too: do not log it.

Do not use the synchronous Codex client inside the block; see the class docstring.

Raises:

RuntimeError – when this instance is already serving.

build_thread_options(**kwargs)[source]

Build the keyword arguments for AsyncCodex.thread_start, with safe defaults.

Defaults approval_mode to ApprovalMode.deny_all and sandbox to Sandbox.read_only, cwd to the empty directory serve() created (so that no project .codex/config.toml or AGENTS.md is found), and ephemeral to True. AsyncCodex always accepts approval requests for command execution and file changes, so the only way to refuse them is to make Codex never ask. A keyword you pass wins. The model and anything else are passed through unchanged.

A nested config["mcp_servers"] table is rewritten into dotted mcp_servers.<name>.<key> keys, because Codex replaces a nested table as a whole at thread level, which would drop this adapter’s own server and its required=true. The dict you pass is not modified.

Call it inside the serve() block.

Raises:
  • RuntimeError – when called outside the serve() block.

  • ValueError – when config is not a dict, or defines an MCP server named server_name (nested or dotted), or its mcp_servers is not a dict, or a server name cannot be written as a dotted key (only letters, digits, _, -, :, @ and / can), or a setting name cannot (only letters, digits, _ and - can), or the same setting is written twice.

async run(turn)[source]

Drive turn, the handle AsyncThread.turn() returns, until it completes.

On a tool failure the model cannot fix, the turn is interrupted before the failure is raised. It is also interrupted when run() is cancelled before the turn completes, for example by a timeout: closing the stream would not stop Codex, which would keep calling tools. The interrupt is a request, bounded to 10 seconds; if it fails, that is logged and does not replace the original exception, and a cancellation still propagates as asyncio.CancelledError. A tool call that arrives while a cancelled run waits for its interrupt, or after this returns or raises, is answered with an isError “Not run” result.

Raises:
  • RuntimeError – when this instance is already running a turn, when the stream ends without a turn/completed notification, or when the turn did not complete (it failed, or was interrupted by something other than a tool failure).

  • ToolCallError – when a tool failed in a way the model cannot fix.

Was this entry helpful?