Lee-W commented on code in PR #74723: URL: https://github.com/apache/airflow/pull/74723#discussion_r4270880153
########## providers/common/ai/docs/features.rst: ########## @@ -17,34 +17,281 @@ .. _howto/features: -LLM and agent features -====================== - -These settings change how a model call or an agent run behaves, independent of which operator -you use. Each is a parameter on the operator or decorator. - -- :doc:`structured_output`: ``output_type`` returns a typed Pydantic object through XCom - instead of a string. -- :doc:`message_history`: ``message_history`` carries a conversation across agent runs. -- :doc:`memory`: pydantic-ai-harness ``Memory`` gives an agent notes it writes in one Dag - run and reads in the next. -- :doc:`capabilities`: ``capabilities=`` adds pydantic-ai capabilities such as ``Thinking`` and - ``WebSearch``, and ``pydantic-ai-shields`` guardrails, to an agent. -- :doc:`code_mode`: the ``CodeMode`` capability lets the model call several tools from one - Python snippet instead of one round trip per call. -- :doc:`approval_gates`: ``require_approval=True`` pauses an LLM operator until a person - approves, edits or rejects the output. -- :doc:`hitl_review`: ``enable_hitl_review=True`` opens an iterative review loop on an agent, - with a chat UI and REST API for the reviewer. -- :doc:`tool_approval`: a tool marked with pydantic-ai's approval API pauses the agent before - the call runs, until a person approves or rejects it. - -The last three are different tools for different jobs: an approval gate is a one-shot decision on -one output, a HITL review is a conversation with a running agent, and a tool approval is a -decision on one action before it happens. - -Making retries cheap with ``durable=True`` is a reliability feature and lives under -:doc:`operations`. +Feature map +=========== + +Most of the provider's operators and decorators run +`Pydantic AI <https://ai.pydantic.dev/>`__ agents, with the model taken from an Airflow +connection. A feature that calls a model through those connections also needs the extra +for your model vendor (:doc:`model_providers`); the **Extra** column lists what it needs +on top of that, and a bare name there is an extra of this provider. :doc:`installation` +lists the features that need a newer Airflow than the provider's 2.11, and +:doc:`stability` says which features are stable. + +Run a model or an agent +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 28 52 20 + + * - Feature + - What it does + - Extra + * - :doc:`@task.llm <operators/llm>` + - Sends one prompt and returns the answer as text or a typed object. + - None + * - :doc:`@task.agent <operators/agent>` + - Runs an agent that calls tools until it has an answer. + - None + * - :doc:`@task.llm_branch <operators/llm_branch>` + - Lets the model pick which downstream tasks run. + - None + * - :doc:`@task.llm_sql <operators/llm_sql>` + - Writes a SQL query from a question and checks it, without running it. + - ``sql``; for files, ``apache-airflow-providers-common-sql[datafusion]`` + * - :doc:`@task.llm_file_analysis <operators/llm_file_analysis>` + - Sends files from object storage, including images and PDFs, to the model with a + prompt. + - ``parquet`` or ``avro`` for those formats + * - :doc:`@task.llm_schema_compare <operators/llm_schema_compare>` + - Compares table schemas across databases and files and grades each mismatch. + - ``common.sql``; for files, ``apache-airflow-providers-common-sql[datafusion]`` + * - :doc:`@task.llm_batch <operators/llm_batch>` + - Sends many prompts through the OpenAI or Anthropic batch API at about half the + per-token price. + - None + * - :doc:`Document and RAG pipelines <rag_pipelines>` + - Loads documents, embeds them and retrieves the passages closest to a question. + - ``llamaindex``, and install the vendor's package for vendors other than OpenAI; + ``pdf`` or ``docx`` for those formats + +Choose a model +-------------- + +.. list-table:: + :header-rows: 1 + :widths: 28 52 20 + + * - Feature + - What it does + - Extra + * - :doc:`Models and providers <model_providers>` + - Takes the vendor, model and key from a connection, so changing vendor is a + connection edit. + - The vendor's, such as ``openai`` or ``anthropic``; the linked page lists each + * - :doc:`Self-hosted models <self_hosted_models>` + - Runs tasks against a model server you host, such as Ollama or vLLM. + - ``openai`` + * - :doc:`Decision models <decision_models>` + - Uses a model that cannot write text, such as TypeSafe's hosted Jev or Ollama's + decision models, to answer a typed question with one value from a set you + define, plus a confidence. + - Jev: ``typesafe``, and install ``pydantic-ai-slim`` 2.45+; others: install + ``pydantic-ai-slim`` 2.53+ + * - :doc:`LlamaIndex models <hooks/llamaindex>` + - Builds LlamaIndex language and embedding models from a connection. + - ``llamaindex``, and install the vendor's package for vendors other than OpenAI + +Give an agent tools +------------------- + +:doc:`toolsets/index` compares what each toolset reaches and how you limit it; +:doc:`agent_security` covers what an agent holding them can reach, with a production +checklist. + +.. list-table:: + :header-rows: 1 + :widths: 28 52 20 + + * - Feature + - What it does + - Extra + * - :doc:`HookToolset <toolsets/hook>` + - Turns the methods you list on any Airflow hook into tools. + - None + * - :doc:`SQLToolset <toolsets/sql>` + - Queries a database, read-only by default, and only the tables in + ``allowed_tables`` when you set it. + - ``sql`` + * - :doc:`ObjectStorageToolset <toolsets/object_storage>` + - Lists and reads files under one object storage path. + - None + * - :doc:`MCPToolset <toolsets/mcp>` + - Gives the agent the tools of an MCP server. + - ``mcp`` + * - :doc:`DataFusionToolset <toolsets/datafusion>` + - Runs SQL over Parquet, CSV and Avro files and Iceberg tables, in the worker. + - ``sql``, plus ``apache-airflow-providers-common-sql[datafusion]``, and its + ``apache.iceberg`` extra for Iceberg + * - :doc:`AgentSkillsToolset <toolsets/skills>` + - Loads ``SKILL.md`` instruction bundles when the model asks for one. + - ``skills``; on Airflow 2, install ``pydantic-ai-skills`` + * - :doc:`SandboxToolset <sandbox/index>` + - Gives the agent a shell and a filesystem in an isolated sandbox: a hosted + service, a server you run, or a microVM on your machine for local development. + - ``modal``, ``islo``, ``opensandbox``, ``openshell`` or ``boat``, by backend; + none for ``sbx`` + * - :doc:`ManagedAgentToolset <toolsets/managed_agent>` + - Sends a prompt to an agent on Bedrock AgentCore or Vertex AI Agent Engine. + - The Amazon or Google provider's ``common.ai`` extra + +Control output and spend +------------------------ + +.. list-table:: + :header-rows: 1 + :widths: 28 52 20 + + * - Feature + - What it does + - Extra + * - :doc:`Structured output <structured_output>` + - Returns a Pydantic object instead of text, on ``@task.llm``, + ``@task.llm_file_analysis`` and ``@task.agent``. + - None + * - :ref:`Usage limits <agent-usage-budget>` + - Fails the task past a cap on requests, tokens, tool calls or estimated cost (for + models pydantic-ai can price), on ``@task.agent`` and every ``@task.llm*`` task + except ``@task.llm_batch``. + - None + +Shape an agent run +------------------ + +These configure ``@task.agent`` and ``AgentOperator``. + +.. list-table:: + :header-rows: 1 + :widths: 28 52 20 + + * - Feature + - What it does + - Extra + * - :doc:`Message history <message_history>` + - Continues a conversation from an earlier run. + - None + * - :doc:`Capabilities and guardrails <capabilities>` + - Turns on model reasoning (``Thinking``), web search (``WebSearch``) and other + Pydantic AI capabilities, and input and output guards. + - ``shields`` for guards + * - :doc:`Code mode <code_mode>` + - Lets the model call several tools from one Python snippet. + - ``code-mode`` + * - :doc:`Agent memory <memory>` + - Pydantic AI's ``Memory`` capability keeps notes the agent writes in one Dag run + and reads in the next. + - None; install ``pydantic-ai-harness`` + * - :ref:`Prompt caching <agent-prompt-caching>` + - Marks the repeated start of each request for caching on Anthropic, and on the + Bedrock and OpenRouter models that support it, so later requests pay less for it; + OpenAI and Gemini cache on their own. On by default. + - None + +Put a person in the loop Review Comment: Probably a good idea to make it human to unity term usage -- 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]
