You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "kaxil (via GitHub)" <gi...@apache.org> on 2026/10/06 22:58:42 UTC
[PR] Add toolset overview and MCP tool filtering example to common.ai docs [airflow]
kaxil opened a new pull request, #74378:
URL: https://github.com/apache/airflow/pull/74378
The toolsets index opened with a long essay on choosing a route, and its first code block was a retry-budget setting. Someone new had to read every guide to find out which toolsets exist and how each one is limited. The index now opens with a table listing each toolset, what the agent gets from it, and the parameters that limit it. Below the table are the two controls that work on any toolset: `.approval_required()` and `.filtered()`.
Other changes:
- **MCP tool filtering.** `.filtered()` is the only allow-list `MCPToolset` has, but the guide described it in prose with no code. A new section, "Offer only some of a server's tools", includes the runnable `example_mcp_filtered_tools` Dag and shows the exact message the model receives when it calls a tool the filter removed.
- **Approval links.** The SQL, hook and MCP guides now link to per-tool approval. They also state that a task instance pauses for approval at most once per Dag run, which rules out gating every SQL `query` call.
- **`ObjectStorageToolset` in the index.** It was missing from the credentials table and the barriers section. It leaves `sequential` unset, so its calls are not barriers. It still shares the process-wide blocking-call lock with the hook, SQL and DataFusion toolsets.
- **Cleanup.**
- Removed duplicated snippets on the DataFusion and Agent Skills pages.
- Fixed a sentence on the object storage page that predates `pinned_arguments`.
- Fixed the `LoggingToolset` snippet, which used an undefined `my_logger` and misdescribed the log lines.
- Renamed a connection ID in `example_mcp.py` that named an internal tool.
The new example Dag ran end to end through `AgentOperator` against a stdio MCP server, once with a scripted model and once with a real one. The message quoted on the page is copied from that run. `breeze build-docs common.ai`, including the spell check, passes.
A companion PR adds a "Restricting the agent" section to five of these guides. The two touch different parts of the same pages and merge cleanly in either order.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add toolset overview and MCP tool filtering example to common.ai docs [airflow]
Posted by "kaxil (via GitHub)" <gi...@apache.org>.
kaxil merged PR #74378:
URL: https://github.com/apache/airflow/pull/74378
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add toolset overview and MCP tool filtering example to common.ai docs [airflow]
Posted by "kaxil (via GitHub)" <gi...@apache.org>.
kaxil commented on code in PR #74378:
URL: https://github.com/apache/airflow/pull/74378#discussion_r4206779809
##########
providers/common/ai/docs/toolsets/index.rst:
##########
@@ -20,27 +20,109 @@
Toolsets
========
+A toolset is a group of tools an agent may call. Pass toolsets to
+:class:`~airflow.providers.common.ai.operators.agent.AgentOperator` or
+``@task.agent`` in ``toolsets=[...]``. The model sees each tool's name, description
+and arguments, and what each call returns. The connection a toolset authenticates
+with is resolved in the worker and is not part of any of that.
+
+.. list-table::
+ :widths: 22 40 38
+ :header-rows: 1
+
+ * - Toolset
+ - What the agent gets
+ - What you limit it with
+ * - :doc:`HookToolset <hook>`
+ - The methods you list from any Airflow hook, one tool per method
+ - ``allowed_methods`` (required), ``pinned_arguments``
+ * - :doc:`SQLToolset <sql>`
+ - ``list_tables``, ``get_schema``, ``query`` and ``check_query`` against a DBAPI
+ database
+ - ``allowed_tables``, ``allow_writes`` (off by default), ``max_rows``,
+ ``max_result_bytes``
+ * - :doc:`ObjectStorageToolset <object_storage>`
+ - ``list_files``, ``get_file_info`` and ``read_file`` under one object-storage path.
+ It cannot write.
+ - ``path``, the root every requested path is checked against;
+ ``max_read_bytes``, ``max_output_bytes``
+ * - :doc:`DataFusionToolset <datafusion>`
+ - SQL over Parquet, CSV and Avro files and Iceberg tables, run in the worker
+ - The tables you register in ``datasource_configs``, ``allow_writes`` (off by
+ default), ``max_rows``
+ * - :doc:`MCPToolset <mcp>`
+ - Every tool the MCP server behind ``mcp_conn_id`` exposes
+ - ``.filtered()`` to offer only some of them
+ * - :doc:`AgentSkillsToolset <skills>`
+ - ``SKILL.md`` instruction bundles that the model loads when it needs one
+ - ``exclude_tools={"run_skill_script"}`` to stop skill scripts running on the
+ worker; ``exclude_resources``
+ * - :doc:`SandboxToolset <../sandbox/index>`
+ - A shell and a filesystem in a sandbox isolated from the worker process
+ - ``SandboxSpec`` (``block_network`` is on by default, ``allow_egress_to``),
+ command timeouts
+ * - :doc:`ManagedAgentToolset <managed_agent>`
+ - One tool that sends a prompt to an agent running on a cloud vendor's
+ infrastructure
+ - ``timeout`` for each call; what the remote agent may touch is set at the
+ vendor
+
+Two controls work on every toolset. ``.approval_required()`` pauses the task before a
+matching call runs, until a person approves or rejects it on the **Required Actions**
+page. It needs Airflow 3.3 or later, pauses a task instance at most once per Dag run,
+and does not combine with ``durable=True`` or a ``SandboxToolset`` that provisions its
+own sandbox (:doc:`../tool_approval` lists every limit). ``.filtered()`` drops tools
+from what the model is offered, as the :ref:`MCP guide <howto/toolset:mcp-filtered>`
+shows.
+
+:doc:`logging` and :doc:`langchain` do not reach a system of their own: one wraps a
+toolset to log its calls, the other converts a toolset for a LangChain agent.
+
+.. toctree::
+ :hidden:
Review Comment:
Went with both `:titlesonly:` and `:hidden:`, matching `use_cases/index.rst`. Dropping `:hidden:` would list every toolset again right under the new table.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add toolset overview and MCP tool filtering example to common.ai docs [airflow]
Posted by "Lee-W (via GitHub)" <gi...@apache.org>.
Lee-W commented on code in PR #74378:
URL: https://github.com/apache/airflow/pull/74378#discussion_r4204766124
##########
providers/common/ai/docs/toolsets/index.rst:
##########
@@ -20,27 +20,109 @@
Toolsets
========
+A toolset is a group of tools an agent may call. Pass toolsets to
+:class:`~airflow.providers.common.ai.operators.agent.AgentOperator` or
+``@task.agent`` in ``toolsets=[...]``. The model sees each tool's name, description
+and arguments, and what each call returns. The connection a toolset authenticates
+with is resolved in the worker and is not part of any of that.
+
+.. list-table::
+ :widths: 22 40 38
+ :header-rows: 1
+
+ * - Toolset
+ - What the agent gets
+ - What you limit it with
+ * - :doc:`HookToolset <hook>`
+ - The methods you list from any Airflow hook, one tool per method
+ - ``allowed_methods`` (required), ``pinned_arguments``
+ * - :doc:`SQLToolset <sql>`
+ - ``list_tables``, ``get_schema``, ``query`` and ``check_query`` against a DBAPI
+ database
+ - ``allowed_tables``, ``allow_writes`` (off by default), ``max_rows``,
+ ``max_result_bytes``
+ * - :doc:`ObjectStorageToolset <object_storage>`
+ - ``list_files``, ``get_file_info`` and ``read_file`` under one object-storage path.
+ It cannot write.
+ - ``path``, the root every requested path is checked against;
+ ``max_read_bytes``, ``max_output_bytes``
+ * - :doc:`DataFusionToolset <datafusion>`
+ - SQL over Parquet, CSV and Avro files and Iceberg tables, run in the worker
+ - The tables you register in ``datasource_configs``, ``allow_writes`` (off by
+ default), ``max_rows``
+ * - :doc:`MCPToolset <mcp>`
+ - Every tool the MCP server behind ``mcp_conn_id`` exposes
+ - ``.filtered()`` to offer only some of them
+ * - :doc:`AgentSkillsToolset <skills>`
+ - ``SKILL.md`` instruction bundles that the model loads when it needs one
+ - ``exclude_tools={"run_skill_script"}`` to stop skill scripts running on the
+ worker; ``exclude_resources``
+ * - :doc:`SandboxToolset <../sandbox/index>`
+ - A shell and a filesystem in a sandbox isolated from the worker process
+ - ``SandboxSpec`` (``block_network`` is on by default, ``allow_egress_to``),
+ command timeouts
+ * - :doc:`ManagedAgentToolset <managed_agent>`
+ - One tool that sends a prompt to an agent running on a cloud vendor's
+ infrastructure
+ - ``timeout`` for each call; what the remote agent may touch is set at the
+ vendor
+
+Two controls work on every toolset. ``.approval_required()`` pauses the task before a
+matching call runs, until a person approves or rejects it on the **Required Actions**
+page. It needs Airflow 3.3 or later, pauses a task instance at most once per Dag run,
+and does not combine with ``durable=True`` or a ``SandboxToolset`` that provisions its
+own sandbox (:doc:`../tool_approval` lists every limit). ``.filtered()`` drops tools
+from what the model is offered, as the :ref:`MCP guide <howto/toolset:mcp-filtered>`
+shows.
+
+:doc:`logging` and :doc:`langchain` do not reach a system of their own: one wraps a
+toolset to log its calls, the other converts a toolset for a LangChain agent.
+
+.. toctree::
+ :hidden:
Review Comment:
```suggestion
:titlesonly:
```
do we want to do this insetad
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org