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¶
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 asSQLToolsetandHookToolset, optionally wrapped with.filtered(),.prefixed()or.renamed()(a.filtered()function runs once, when this is built, withctx.depsset toNone), or individualAirflowToolobjects. Codex has no in-process tools, soserve()starts an MCP server on127.0.0.1in the running event loop and points acodex app-serverchild process at it. Start a thread withbuild_thread_options()and drive its turn withrun():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
isErrortool result. A failure the model cannot fix, such as a hook raising, makesrun()raiseToolCallError, 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 synchronousCodexcall 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 newAirflowToolsper task. A tool call that arrives after a run has ended is refused until the nextrun()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_namehas other characters.
- async serve()[source]¶
Serve the tools over MCP for the duration of the block and yield the
CodexConfigto use.Creates an empty
CODEX_HOME, an empty working directory and an emptyHOMEin a temporary directory, starts the MCP server on a free127.0.0.1port with a random bearer token, and yields aCodexConfigthat pointscodex app-serverat 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 theAsyncCodexthat uses it.The yielded
CodexConfigholds the bearer token inenv, so itsreprdoes too: do not log it.Do not use the synchronous
Codexclient 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_modetoApprovalMode.deny_allandsandboxtoSandbox.read_only,cwdto the empty directoryserve()created (so that no project.codex/config.tomlorAGENTS.mdis found), andephemeraltoTrue.AsyncCodexalways 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 dottedmcp_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 itsrequired=true. The dict you pass is not modified.Call it inside the
serve()block.- Raises:
RuntimeError – when called outside the
serve()block.ValueError – when
configis not a dict, or defines an MCP server namedserver_name(nested or dotted), or itsmcp_serversis 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 handleAsyncThread.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 asasyncio.CancelledError. A tool call that arrives while a cancelled run waits for its interrupt, or after this returns or raises, is answered with anisError“Not run” result.- Raises:
RuntimeError – when this instance is already running a turn, when the stream ends without a
turn/completednotification, 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.