This is an automated email from the ASF dual-hosted git repository.
kaxil pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 7eac9ac7c1b Add connections and agent-security entries to the
common.ai sidebar (#73837)
7eac9ac7c1b is described below
commit 7eac9ac7c1b82de23b3843424dfea934ac2dbf61
Author: Kaxil Naik <[email protected]>
AuthorDate: Mon Sep 28 13:18:37 2026 +0100
Add connections and agent-security entries to the common.ai sidebar (#73837)
Reviewer feedback on the reorganized sidebar raised three gaps. The
Security entry, which the provider docs template fixes to the
vulnerability-reporting policy, sits prominently in Basics and reads as
if it were about securing agents; the Securing agent tools page now sits
directly under it, and opens by naming both sides of agent security, the
tools an agent can reach and the data that flows in and out. Connections
had no top-level entry after the reorg although readers go to them
often; a new Connections page lists the seven connection types with what
each is for and links to the reference for each. The Operators entry is
now "Operators and decorators", since every decorator is an operator
underneath and readers looking for @task.llm did not find it.
---
providers/common/ai/docs/agent_security.rst | 22 ++++++++-
providers/common/ai/docs/connections/index.rst | 62 ++++++++++++++++++++++++++
providers/common/ai/docs/index.rst | 4 +-
providers/common/ai/docs/operations.rst | 1 -
providers/common/ai/docs/operators/index.rst | 4 +-
5 files changed, 88 insertions(+), 5 deletions(-)
diff --git a/providers/common/ai/docs/agent_security.rst
b/providers/common/ai/docs/agent_security.rst
index 04b7b4c5411..41b1e236245 100644
--- a/providers/common/ai/docs/agent_security.rst
+++ b/providers/common/ai/docs/agent_security.rst
@@ -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.
diff --git a/providers/common/ai/docs/connections/index.rst
b/providers/common/ai/docs/connections/index.rst
new file mode 100644
index 00000000000..1068ac542ee
--- /dev/null
+++ b/providers/common/ai/docs/connections/index.rst
@@ -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`.
diff --git a/providers/common/ai/docs/index.rst
b/providers/common/ai/docs/index.rst
index 0da4eec1bde..d986d937455 100644
--- a/providers/common/ai/docs/index.rst
+++ b/providers/common/ai/docs/index.rst
@@ -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>
diff --git a/providers/common/ai/docs/operations.rst
b/providers/common/ai/docs/operations.rst
index 77226593e30..9a0ddb28025 100644
--- a/providers/common/ai/docs/operations.rst
+++ b/providers/common/ai/docs/operations.rst
@@ -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>
diff --git a/providers/common/ai/docs/operators/index.rst
b/providers/common/ai/docs/operators/index.rst
index 4b4ffb9f1d7..67ba23eb9c5 100644
--- a/providers/common/ai/docs/operators/index.rst
+++ b/providers/common/ai/docs/operators/index.rst
@@ -15,8 +15,8 @@
specific language governing permissions and limitations
under the License.
-Choosing an operator
-====================
+Operators and decorators
+========================
By use case
-----------
