Skip to content

Add connections and agent-security entries to the common.ai sidebar - #73837

Merged
kaxil merged 1 commit into
apache:mainfrom
astronomer:commonai-docs-feedback
Sep 28, 2026
Merged

kaxil merged 1 commit into
apache:mainfrom
astronomer:commonai-docs-feedback

Conversation

@kaxil

@kaxil kaxil commented Sep 28, 2026

Copy link
Copy Markdown
Member

Three sidebar changes from reviewer feedback on the reorganized common.ai docs.

Securing agent tools sits under Security. The Security entry in Basics is fixed by the provider docs template to the vulnerability-reporting policy, and its prominence makes it read as the place to learn about securing agents. That page cannot change, so the agent-security page now appears directly beneath it in the sidebar, and its opening names both sides of the problem: what the agent can reach (tools, connections, limits, which the provider controls) and what flows in and out (sensitive data in the context when a tool reaches an untrusted source, and the agent's output as untrusted input downstream, which the Dag author controls). The closing checklist gains an output-handling item and a sentence on tools that read untrusted sources. The page leaves the Reliability and operations toctree so it has one parent; the prose link there stays.

Connections is a top-level guide again. The reorg folded the seven connection pages under Models and providers, and readers who go straight to connection setup did not find them. A new connections/index.rst lists each connection type with what it is for and links to its reference page. It links rather than nests, since the pages already belong to the providers toctree.

Operators is now "Operators and decorators". Every @task.* decorator is an operator underneath, and readers looking for the decorators did not open the operators entry. The page heading matches.

No page moves, so no redirects.


  • Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
  • For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
  • When adding dependency, check compliance with the ASF 3rd Party License Policy.
  • For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

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.
@kaxil
kaxil force-pushed the commonai-docs-feedback branch from 39a17f5 to 7d3844a Compare September 28, 2026 11:47
@kaxil
kaxil marked this pull request as ready for review September 28, 2026 11:47
@kaxil
kaxil merged commit 7eac9ac into apache:main Sep 28, 2026
70 checks passed
@kaxil
kaxil deleted the commonai-docs-feedback branch September 28, 2026 12:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants