kaxil · Sep 28, 2026 · Sep 28, 2026
@@ -21,6 +21,19 @@ Securing agent tools
 LLM agents call tools based on natural-language reasoning. This makes them
 powerful but introduces risks that don't exist with deterministic operators.
 
+Securing an agent has two sides. The first is what the agent can reach: the
+tools you register, the connections behind them, and the limits on each. Most
+of this page is about that side, because it is where the provider gives you
+controls. The second side is what reaches the agent and what leaves it, and
+that one belongs to the Dag author: keep sensitive data out of the prompt and
+the tool results when the agent can also reach an untrusted system such as the
+web, and treat the agent's output as untrusted input for whatever consumes it
+downstream. The :ref:`checklist <agent-security-checklist>` at the end covers
+both.
+
+The :doc:`security` page is the provider's vulnerability-reporting policy, not a
+guide to securing agents.
+
 What the agent can and cannot reach
 -------------------------------------
 
@@ -241,6 +254,8 @@ Recommended configuration
         max_rows=100,
     )
 
+.. _agent-security-checklist:
+
 Production checklist
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -264,4 +279,9 @@ Before deploying an agent task to production:
    "Only query tables related to the question. Never modify data.").
 8. **Prompt injection**: Be cautious when the prompt includes untrusted data
    (user input, external API responses, upstream XCom). Consider sanitizing
-   inputs before passing them to the agent.
+   inputs before passing them to the agent. A tool that reads an untrusted
+   source, a web page or a shared inbox for example, brings that text into the
+   context too, so do not pair such a tool with sensitive data in the same run.
+9. **Output handling**: The agent's answer is model output. Validate it with
+   ``output_type`` where a shape is expected, and treat free text as untrusted
+   before a downstream task acts on it, posts it, or writes it somewhere.
@@ -0,0 +1,62 @@
+ .. 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.
+
+Connections
+===========
+
+Every model call and every MCP server in this provider goes through an Airflow
+connection. The connection holds the credential and, for model connections, the model
+name in ``provider:model`` form, so a Dag names a connection id and never a key or a
+vendor. Create connections in the UI under **Admin > Connections**, with an
+``AIRFLOW_CONN_<ID>`` environment variable, or through a secrets backend.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 38 40
+
+   * - Connection type
+     - Use it for
+     - Page
+   * - ``pydanticai``
+     - Any vendor pydantic-ai supports through an API key and an optional base URL:
+       OpenAI, Anthropic, Google Gemini, Groq, Mistral, DeepSeek, Ollama, vLLM,
+       TypeSafe and others. The default for every operator and decorator.
+     - :doc:`pydantic_ai`
+   * - ``pydanticai_azure``
+     - Azure OpenAI, with the endpoint and API version Azure needs.
+     - :doc:`pydantic_ai_azure`
+   * - ``pydanticai_bedrock``
+     - AWS Bedrock, with IAM keys, a bearer token or the default credential chain.
+     - :doc:`pydantic_ai_bedrock`
+   * - ``pydanticai_vertex``
+     - Google Vertex AI, with a project, a location and a service account.
+     - :doc:`pydantic_ai_vertex`
+   * - ``mcp``
+     - An MCP server the agent calls as a toolset, over HTTP, SSE or a stdio subprocess.
+     - :doc:`mcp`
+   * - ``langchain``
+     - Chat and embedding models built through LangChain, for the LangChain hook and
+       toolset bridge.
+     - :doc:`langchain`
+   * - ``llamaindex``
+     - OpenAI models for the LlamaIndex embedding and retrieval operators.
+     - :doc:`llamaindex`
+
+Which vendors work, and the extra and model prefix each one needs, is on
+:doc:`../model_providers`. Vendor outages can fail over to a second connection with
+:doc:`../provider_fallback`. Error messages from a misconfigured connection are listed
+with their fixes in :doc:`../troubleshooting`.
@@ -85,6 +85,7 @@ waits for the result, use that vendor's provider.
     Home <self>
     Changelog <changelog>
     Security <security>
+    Securing agent tools <agent_security>
 
 .. toctree::
     :titlesonly:
@@ -102,8 +103,9 @@ waits for the result, use that vendor's provider.
     :caption: Guides
 
     What you can build <use_cases/index>
+    Connections <connections/index>
     Models and providers <model_providers>
-    Operators <operators/index>
+    Operators and decorators <operators/index>
     Toolsets <toolsets/index>
     LLM and agent features <features>
     Document and RAG pipelines <rag_pipelines>

@@ -41,5 +41,4 @@ An AI task fails in more ways than a SQL task, and it costs money each time it r
     Durable execution <durable_execution>
     Retry policies <retry_policies>
     Observability <observability>
-    Securing agent tools <agent_security>
     Troubleshooting <troubleshooting>
@@ -15,8 +15,8 @@
     specific language governing permissions and limitations
     under the License.
 
-Choosing an operator
-====================
+Operators and decorators
+========================
 
 By use case
 -----------