Lee-W commented on code in PR #72936: URL: https://github.com/apache/airflow/pull/72936#discussion_r4045927358
########## providers/common/ai/docs/choosing_a_toolset.rst: ########## @@ -0,0 +1,533 @@ + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. _howto/choosing-a-toolset: + +Choosing a Toolset +================== + +:doc:`toolsets` documents how to configure each toolset. This page answers the +question that comes before that one: you have a system you want an agent to +reach, so which route do you take, and what does each route give up? + +Read the table below by what you already have, not by what a toolset is called. +When two routes both work, the deciding factor is rarely what each one can do — +it is what each one cannot do, and every route has a short list. + +More than one row can be true at once, and the rows are not exclusive: one agent +can carry several toolsets. Two questions break the ties. *Whose credential is +it?* — prefer the route whose credential is an Airflow connection somebody on +your side already reviewed. *Whose tool list is it?* — prefer the route whose +exposed surface you chose rather than inherited. The pair that most often +overlaps is an Airflow hook and a vendor MCP server reaching the same target; +both questions point at the hook, because its credential is the connection and +``allowed_methods`` is a list you write. Reach for the server when its tools +cover work the hook does not expose, or when the alternative is re-wrapping that +API by hand. + +Those two questions do not separate ``HookToolset`` from ``SQLToolset`` when the +target is a DBAPI database, because both answer them the same way. A third one +does: *is the work a fixed operation or an open-ended question?* A named method +you can enumerate in advance is a hook. A question the agent has to express as +SQL is a query, and ``SQLToolset`` answers it with schema discovery, bounded +results and an ``allowed_tables`` walk you can switch on, none of which +``HookToolset`` has an equivalent of. + +Start with what you have +------------------------ + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - What you have + - Route + * - A target that already has an Airflow connection, and a hook method that + already does the thing + - ``HookToolset`` + * - A question that is a query, against a DBAPI database + - ``SQLToolset`` + * - Files on an object store — Parquet, CSV, Avro, Iceberg — rather than rows Review Comment: the decision-table row and the section now separate object-store formats from a catalog-managed one: parquet, csv and avro take a `uri`, iceberg is looked up by `db_name`, and `datasourceconfig` raises at construction if a catalog format is missing it. added a second, iceberg-shaped example following the config in `example_analytics.py`, so the page no longer offers only the parquet one to copy. -- 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]
