kaxil opened a new pull request, #74685: URL: https://github.com/apache/airflow/pull/74685
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. -- 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]
