airflow.providers.common.ai.tools¶

Framework-neutral tools backed by Airflow connections.

An AirflowTool is one operation an agent can call: a name, a description, a JSON Schema for its arguments, and an async function. Nothing in it belongs to a particular agent framework, so the same tool can be handed to Strands Agents, Google ADK or LangChain through a small adapter, while the agent itself stays native to that framework.

The toolsets this provider ships, such as SQLToolset and HookToolset, implement ToolProvider and expose their tools through ToolProvider.airflow_tools().

Note

Experimental: this interface can change or be removed in a minor release of this provider. See Stable and experimental features.

Submodules¶

Exceptions¶

ToolCallError

A tool call failed in a way the model cannot fix by changing its arguments.

Classes¶

`ToolResult`	The outcome of one tool call, as the agent framework receives it.
`AirflowTool`	One operation an agent can call, independent of any agent framework.
`ToolProvider`	A source of `AirflowTool` objects, such as a toolset bound to one connection.

Functions¶

collect_tools(sources)

Flatten toolsets and individual tools, as a framework adapter receives them, into tools.

Package Contents¶

exception airflow.providers.common.ai.tools.ToolCallError[source]¶

Bases: Exception

A tool call failed in a way the model cannot fix by changing its arguments.

The message has already been through Airflow’s secret masker. Adapters let it propagate so the agent run, and with it the task, fails and Airflow’s retry handles it, the same way an unhandled tool error fails an AgentOperator run.

class airflow.providers.common.ai.tools.ToolResult[source]¶

The outcome of one tool call, as the agent framework receives it.

Parameters:

content – What the model sees. A string or any JSON-compatible value.
is_error – Whether the call failed in a way the model can correct, such as a query naming a column that does not exist. Adapters map this to the framework’s own error status, so a failure is never inferred from the text of content.

content: pydantic.JsonValue[source]¶

is_error: bool = False[source]¶

class airflow.providers.common.ai.tools.AirflowTool[source]¶

One operation an agent can call, independent of any agent framework.

Call it through call(), never function directly: call() is the one path every adapter shares, and it is where Airflow’s secret masker runs on everything returned to the model.

Parameters:

name – Tool name shown to the model.
description – What the tool does, shown to the model.
parameters – JSON Schema ("type": "object") for the tool’s arguments.
function – Async function that performs the operation. It receives the arguments the model supplied and returns a ToolResult. It returns an error result for a failure the model can correct, and raises for anything else.

name: str[source]¶

description: str[source]¶

parameters: dict[str, Any][source]¶

function: collections.abc.Callable[[dict[str, Any]], collections.abc.Awaitable[ToolResult]][source]¶

async call(arguments)[source]¶

Run the tool and return a result that is safe to hand back to the model.

The content of the result, including error text, passes through Airflow’s secret masker, so a connection password that ends up in a result is replaced with *** before it reaches the model, the model provider, or anything the framework records. The masker only knows secrets Airflow has registered, such as connection passwords and sensitive connection extras.

Raises:: ToolCallError – when function raises. The original exception is logged to the task log, which masks it; only the masked message travels on, because frameworks record a failed call’s exception, cause included, in their traces.

class airflow.providers.common.ai.tools.ToolProvider[source]¶

Bases: Protocol

A source of AirflowTool objects, such as a toolset bound to one connection.

airflow_tools()[source]¶

Return the tools this provider exposes.

airflow.providers.common.ai.tools.collect_tools(sources)[source]¶

Flatten toolsets and individual tools, as a framework adapter receives them, into tools.

Raises:: ValueError – when two tools share a name. Frameworks route a call by name, so one of them would silently never run; give one toolset a tool name prefix.