Skip to content

Commit eddaa67

Browse files
Add AWS services toolset for agents to access 1000+ APIs (#70087)
* Add AWS services toolset for agents to access 1000+ APIs * Fix basic tests * Fix basic tests * Move to helpers * resolve comments * Add more tests * Update description * parametrize tests
1 parent 5227a91 commit eddaa67

10 files changed

Lines changed: 1036 additions & 16 deletions

File tree

‎dev/breeze/tests/test_selective_checks.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1109,7 +1109,7 @@ def assert_outputs_are_printed(expected_outputs: dict[str, str], stderr: str):
11091109
pytest.param(
11101110
("providers/amazon/src/airflow/providers/amazon/provider.yaml",),
11111111
{
1112-
"selected-providers-list-as-string": "amazon apache.hive cncf.kubernetes "
1112+
"selected-providers-list-as-string": "amazon apache.hive cncf.kubernetes common.ai "
11131113
"common.compat common.messaging common.sql databricks exasol ftp google http imap microsoft.azure "
11141114
"mongo mysql openlineage postgres salesforce ssh teradata",
11151115
"all-python-versions": f"['{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}']",
@@ -1136,9 +1136,9 @@ def assert_outputs_are_printed(expected_outputs: dict[str, str], stderr: str):
11361136
{
11371137
"description": "amazon...google",
11381138
"test_types": "Providers[amazon] Providers[apache.hive,cncf.kubernetes,"
1139-
"common.compat,common.messaging,common.sql,databricks,exasol,ftp,http,imap,"
1140-
"microsoft.azure,mongo,mysql,openlineage,postgres,salesforce,ssh,teradata] "
1141-
"Providers[google]",
1139+
"common.ai,common.compat,common.messaging,common.sql,databricks,exasol,ftp,"
1140+
"http,imap,microsoft.azure,mongo,mysql,openlineage,postgres,salesforce,ssh,"
1141+
"teradata] Providers[google]",
11421142
}
11431143
]
11441144
),
@@ -1181,7 +1181,7 @@ def assert_outputs_are_printed(expected_outputs: dict[str, str], stderr: str):
11811181
pytest.param(
11821182
("providers/amazon/src/airflow/providers/amazon/file.py",),
11831183
{
1184-
"selected-providers-list-as-string": "amazon apache.hive cncf.kubernetes "
1184+
"selected-providers-list-as-string": "amazon apache.hive cncf.kubernetes common.ai "
11851185
"common.compat common.messaging common.sql databricks exasol ftp google http imap microsoft.azure "
11861186
"mongo mysql openlineage postgres salesforce ssh teradata",
11871187
"all-python-versions": f"['{DEFAULT_PYTHON_MAJOR_MINOR_VERSION}']",
@@ -1205,9 +1205,9 @@ def assert_outputs_are_printed(expected_outputs: dict[str, str], stderr: str):
12051205
{
12061206
"description": "amazon...google",
12071207
"test_types": "Providers[amazon] Providers[apache.hive,cncf.kubernetes,"
1208-
"common.compat,common.messaging,common.sql,databricks,exasol,ftp,http,imap,"
1209-
"microsoft.azure,mongo,mysql,openlineage,postgres,salesforce,ssh,teradata] "
1210-
"Providers[google]",
1208+
"common.ai,common.compat,common.messaging,common.sql,databricks,exasol,ftp,"
1209+
"http,imap,microsoft.azure,mongo,mysql,openlineage,postgres,salesforce,ssh,"
1210+
"teradata] Providers[google]",
12111211
}
12121212
]
12131213
),

‎providers/common/ai/docs/examples.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,9 @@ Agents & tools
6969
`example_agent_capabilities.py <https://github.com/apache/airflow/blob/providers-common-ai/|version|/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_agent_capabilities.py>`__).
7070
* - :ref:`Toolsets <howto/toolsets>`
7171
- Loading ``SKILL.md`` Agent Skills
72-
(`example_agent_skills.py <https://github.com/apache/airflow/blob/providers-common-ai/|version|/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_agent_skills.py>`__)
72+
(`example_agent_skills.py <https://github.com/apache/airflow/blob/providers-common-ai/|version|/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_agent_skills.py>`__),
73+
allow-listed AWS API access via ``AWSToolset``
74+
(`example_aws_toolset.py <https://github.com/apache/airflow/blob/providers-common-ai/|version|/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_aws_toolset.py>`__),
7375
and exposing an Airflow toolset to a LangChain agent, the reverse bridge
7476
(`example_langchain_toolset_bridge.py <https://github.com/apache/airflow/blob/providers-common-ai/|version|/providers/common/ai/src/airflow/providers/common/ai/example_dags/example_langchain_toolset_bridge.py>`__).
7577
* - :doc:`connections/mcp`

‎providers/common/ai/docs/index.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,12 +217,13 @@ You can install such cross-provider dependencies when installing from PyPI. For
217217

218218
.. code-block:: bash
219219
220-
pip install apache-airflow-providers-common-ai[common.sql]
220+
pip install apache-airflow-providers-common-ai[amazon]
221221
222222
223223
============================================================================================================ ==============
224224
Dependent package Extra
225225
============================================================================================================ ==============
226+
`apache-airflow-providers-amazon <https://airflow.apache.org/docs/apache-airflow-providers-amazon>`_ ``amazon``
226227
`apache-airflow-providers-common-sql <https://airflow.apache.org/docs/apache-airflow-providers-common-sql>`_ ``common.sql``
227228
`apache-airflow-providers-git <https://airflow.apache.org/docs/apache-airflow-providers-git>`_ ``git``
228229
============================================================================================================ ==============
@@ -252,12 +253,14 @@ Extra Dependencies
252253
``avro`` ``fastavro>=1.10.0; python_version < "3.14"``, ``fastavro>=1.12.1; python_version >= "3.14"``
253254
``parquet`` ``pyarrow>=18.0.0; python_version < '3.14'``, ``pyarrow>=22.0.0; python_version >= '3.14'``
254255
``sql`` ``apache-airflow-providers-common-sql``, ``sqlglot>=30.0.0``
256+
``aws`` ``apache-airflow-providers-amazon>=9.0.0``
255257
``common.sql`` ``apache-airflow-providers-common-sql``
256258
``langchain`` ``langchain>=1.0.0``
257259
``llamaindex`` ``dataclasses-json>=0.6.7``, ``llama-index-core>=0.13.0``, ``llama-index-embeddings-openai>=0.6.0``, ``llama-index-llms-openai>=0.6.0``
258260
``pdf`` ``pypdf>=4.0.0``
259261
``docx`` ``python-docx>=1.0.0``
260262
``git`` ``apache-airflow-providers-git``
263+
``amazon`` ``apache-airflow-providers-amazon``
261264
============== =======================================================================================================================================
262265

263266
Downloading official packages

‎providers/common/ai/docs/toolsets.rst‎

Lines changed: 70 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,17 +24,20 @@ Airflow's 350+ provider hooks already have typed methods, rich docstrings,
2424
and managed credentials. Toolsets expose them as pydantic-ai tools so that
2525
LLM agents can call them during multi-turn reasoning.
2626

27-
Three toolsets are included:
27+
Four toolsets are included:
2828

29+
- :class:`~airflow.providers.common.ai.toolsets.aws.AWSToolset` — configured
30+
AWS services toolset for agent access to AWS APIs through Airflow-managed
31+
AWS connections.
2932
- :class:`~airflow.providers.common.ai.toolsets.hook.HookToolset` — generic
3033
adapter for any Airflow Hook.
31-
- :class:`~airflow.providers.common.ai.toolsets.sql.SQLToolset` — curated
32-
4-tool database toolset.
3334
- :class:`~airflow.providers.common.ai.toolsets.mcp.MCPToolset` — connect to
3435
`MCP servers <https://modelcontextprotocol.io/>`__ configured via Airflow
3536
connections.
37+
- :class:`~airflow.providers.common.ai.toolsets.sql.SQLToolset` — curated
38+
4-tool database toolset.
3639

37-
All three implement pydantic-ai's
40+
All four implement pydantic-ai's
3841
`AbstractToolset <https://ai.pydantic.dev/toolsets/>`__ interface and can be
3942
passed to any pydantic-ai ``Agent``, including via
4043
:class:`~airflow.providers.common.ai.operators.agent.AgentOperator`.
@@ -263,6 +266,69 @@ Parameters
263266
support DDL for in-memory tables; this guard blocks those by default.
264267
- ``max_rows``: Maximum rows returned from the ``query`` tool. Default ``50``.
265268

269+
``AWSToolset``
270+
--------------
271+
272+
Curated toolset that gives an agent allow-listed access to AWS APIs with
273+
three tools:
274+
275+
.. list-table::
276+
:header-rows: 1
277+
:widths: 20 50
278+
279+
* - Tool
280+
- Description
281+
* - ``list_aws_operations``
282+
- Lists the operations the toolset allows, grouped by service
283+
* - ``describe_aws_operation``
284+
- Returns an operation's parameter and response shapes (from the
285+
botocore service model), so the agent can check what a call expects
286+
before making it
287+
* - ``call_aws``
288+
- Executes an allowed operation and returns the response as JSON,
289+
aggregating paginated results
290+
291+
Credentials, region, and session configuration come from the Airflow
292+
connection (``aws_conn_id``) via the amazon provider — the model cannot
293+
override them through tool arguments. Requires the ``aws`` extra::
294+
295+
pip install "apache-airflow-providers-common-ai[aws]"
296+
297+
.. exampleinclude:: /../../ai/src/airflow/providers/common/ai/example_dags/example_aws_toolset.py
298+
:language: python
299+
:start-after: [START howto_operator_agent_aws]
300+
:end-before: [END howto_operator_agent_aws]
301+
302+
Access is deny-by-default: ``allowed_actions`` is required and supports ``*``
303+
wildcards in the operation part only (``"athena:*"``, ``"s3:List*"``).
304+
Operations that return credentials or decrypted secrets — ``sts:AssumeRole``,
305+
``secretsmanager:GetSecretValue``, ``kms:Decrypt``, and similar — are never
306+
matched by a wildcard and must be listed verbatim to be callable.
307+
308+
.. warning::
309+
``allowed_actions`` bounds what the agent can ask for, not what the
310+
credentials can do. Point ``aws_conn_id`` at a least-privilege IAM role
311+
scoped to the same operations.
312+
313+
Parameters
314+
^^^^^^^^^^
315+
316+
- ``aws_conn_id``: Airflow connection ID for AWS credentials. Default
317+
``aws_default``.
318+
- ``allowed_actions``: Operations the agent may call, in
319+
``"<service>:<Operation>"`` form using boto3 service names and API
320+
operation names. Required — there is no auto-discovery. Matching is case-
321+
and underscore-insensitive, so ``"s3:list_buckets"`` equals
322+
``"s3:ListBuckets"``. Validated against botocore's bundled service
323+
definitions at instantiation time (local metadata only — no network, no
324+
credentials).
325+
- ``region_name``: AWS region for API calls. Default ``None`` — use the
326+
region configured on the connection.
327+
- ``max_items``: Upper bound on items aggregated from paginated operations.
328+
Default ``1000``.
329+
- ``max_output_bytes``: Upper bound on the serialized response returned to
330+
the agent; larger payloads are clipped and flagged. Default ``65536``.
331+
266332
``LoggingToolset``
267333
------------------
268334

‎providers/common/ai/pyproject.toml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,11 @@ dependencies = [
108108
"apache-airflow-providers-common-sql",
109109
"sqlglot>=30.0.0",
110110
]
111+
# AWSToolset: allow-listed AWS API access for agents. The amazon provider
112+
# supplies credential resolution (AwsBaseHook) and brings boto3/botocore.
113+
"aws" = [
114+
"apache-airflow-providers-amazon>=9.0.0",
115+
]
111116
"common.sql" = [
112117
"apache-airflow-providers-common-sql"
113118
]
@@ -125,12 +130,16 @@ dependencies = [
125130
"git" = [
126131
"apache-airflow-providers-git"
127132
]
133+
"amazon" = [
134+
"apache-airflow-providers-amazon"
135+
]
128136

129137
[dependency-groups]
130138
dev = [
131139
"apache-airflow",
132140
"apache-airflow-task-sdk",
133141
"apache-airflow-devel-common",
142+
"apache-airflow-providers-amazon",
134143
"apache-airflow-providers-common-compat",
135144
"apache-airflow-providers-common-sql",
136145
"apache-airflow-providers-git",
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
"""Example Dag: agent with allow-listed AWS access via AWSToolset."""
18+
19+
from __future__ import annotations
20+
21+
from airflow.providers.common.ai.operators.agent import AgentOperator
22+
from airflow.providers.common.ai.toolsets.aws import AWSToolset
23+
from airflow.providers.common.compat.sdk import dag
24+
25+
26+
# [START howto_operator_agent_aws]
27+
@dag(tags=["example"])
28+
def example_agent_aws_toolset():
29+
AgentOperator(
30+
task_id="s3_auditor",
31+
prompt="Which buckets exist, and roughly how much data is in 'data-lake-raw'?",
32+
llm_conn_id="pydanticai_default",
33+
system_prompt=(
34+
"You are an AWS operations assistant. Discover what you are allowed "
35+
"to call, check parameter shapes before calling, and answer with "
36+
"concrete numbers."
37+
),
38+
toolsets=[
39+
AWSToolset(
40+
aws_conn_id="aws_default",
41+
allowed_actions=[
42+
"s3:ListBuckets",
43+
"s3:ListObjectsV2",
44+
"s3:GetBucketLocation",
45+
],
46+
region_name="us-east-1",
47+
)
48+
],
49+
)
50+
51+
52+
# [END howto_operator_agent_aws]
53+
54+
example_agent_aws_toolset()

‎providers/common/ai/src/airflow/providers/common/ai/toolsets/__init__.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
from airflow.providers.common.ai.toolsets.hook import HookToolset
2222

23-
__all__ = ["HookToolset", "MCPToolset", "SQLToolset", "airflow_toolset_to_langchain_tools"]
23+
__all__ = ["AWSToolset", "HookToolset", "MCPToolset", "SQLToolset", "airflow_toolset_to_langchain_tools"]
2424

2525

2626
def __getattr__(name: str):
@@ -46,4 +46,12 @@ def __getattr__(name: str):
4646

4747
raise AirflowOptionalProviderFeatureException(e)
4848
return MCPToolset
49+
if name == "AWSToolset":
50+
try:
51+
from airflow.providers.common.ai.toolsets.aws import AWSToolset
52+
except ImportError as e:
53+
from airflow.providers.common.compat.sdk import AirflowOptionalProviderFeatureException
54+
55+
raise AirflowOptionalProviderFeatureException() from e
56+
return AWSToolset
4957
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

0 commit comments

Comments
 (0)