[kaxil]

Nothing in the Common AI docs answers the first question a newcomer asks: what does this give me over a Pydantic AI agent, or a vendor SDK, in a plain @task, and when should I not use it? The landing page's answer was "the API key comes from a connection, a failed call retries, a run can pause for approval, the result lands in XCom, it runs on a schedule". Four of those five apply to any task. Someone reading the published docs from the landing page as a first-time user lost confidence at exactly that sentence.

This adds why_common_ai.rst, linked from the landing page's first screen and the "Getting started" toctree:

• The same job two ways. First comes the code you would write without the provider: a model string, a key from the environment, and hand-written tools. A new runnable example, example_why_common_ai.py, shows the same job with AgentOperator. The differences are stated concretely: what the hand-written query tool allows compared with SQLToolset, model from a connection, replay on retry, and a spend cap across attempts.
• What a plain task leaves to you. A table, one row per situation: retry replay, the cross-attempt usage_limits budget, output approval, tool approval, multi-round review, tools from connections, fallback_conn_ids, and batch. Each row says what the provider does and links the page that documents it.
• Retry policies. Presented as working on any task, including one that never calls a model.
• When a plain task is enough. Said plainly.

It also rewrites the landing paragraph to name what is specific to the provider.

The page argues for the provider, so every claim was checked against the source. Experimental features (durable, tool approval, batch, ObjectStorageToolset, ClassifierRetryPolicy) are labelled as such. Each pause says whether it holds a worker:

• Approval gates and tool approval don't hold one.
• enable_hitl_review polls and holds one.
• For a single approve or reject of an agent's answer, the page points to the standard provider's ApprovalOperator.

Version floors are stated per row.

The plain-task baseline is a code-block, not a shipped example. Its query tool runs whatever SQL the model writes, which is the point of the comparison. It is not something to put in example_dags for people to copy.

The AgentOperator example passes the example-Dag import tests and mypy. It has not been run against a real model or database.

Follow-ups

Found while reading the docs as a newcomer, and left out of this PR:

• hitl_review.rst never says the review plugin is registered by the provider, so readers look for an install step.
• concepts.rst uses "agent loop" before defining it.