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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
