Add Vertex AI Agent Engine operators (Create, Get, Query, Update, Delete)

[AlejandroMorgante]

Add a hook, operators, deferrable trigger support, unit tests, docs, and a system test for the Vertex AI Agent Engine (Reasoning Engine) API.

Operators

• CreateAgentEngineOperator - creates a new Agent Engine resource.
• GetAgentEngineOperator - retrieves an existing Agent Engine.
• RunQueryJobOperator - starts a query job using the public run_query_job SDK method and can wait for completion, including deferrable mode.
• UpdateAgentEngineOperator - updates an Agent Engine.
• DeleteAgentEngineOperator - deletes an Agent Engine, with optional wait support.

Review-driven changes

This PR was updated based on review feedback to avoid relying on private SDK helpers and to keep the Airflow task semantics explicit:

• Replaced the previous direct/private query path with the public run_query_job API.
• Added RunQueryJobOperator support for waiting on query jobs and retrieving query output through check_query_job.
• Added AgentEngineQueryJobTrigger for deferrable query-job waiting.
• Updated delete waiting to follow the delete operation result instead of polling the Agent Engine resource until a 404.
• Removed the deleted-resource polling helper that was no longer needed.
• Made the system test self-contained: it builds the agent container image with Cloud Build, pushes it to an Artifact Registry repository scoped to the test run, creates the query-output GCS bucket, and deletes those resources during teardown.

Changes

• providers/google/cloud/hooks/vertex_ai/agent_engine.py - new Agent Engine hook methods.
• providers/google/cloud/operators/vertex_ai/agent_engine.py - new Agent Engine operators.
• providers/google/cloud/triggers/vertex_ai.py - Agent Engine query-job trigger.
• providers/google/provider.yaml - hook and operator registration.
• providers/google/get_provider_info.py - matching provider metadata registration.
• providers/google/docs/operators/cloud/vertex_ai.rst - Agent Engine operator docs.
• providers/google/tests/system/google/cloud/vertex_ai/example_vertex_ai_agent_engine.py - self-contained Agent Engine lifecycle system test.
• Unit tests for hook, operators, and triggers.

Validation

Validated end-to-end against a real GCP environment, including create, get, query-job submission, query-job output retrieval, update, and delete flows.

The complete system test can be reproduced from the Airflow checkout with GCP credentials forwarded to Breeze, SYSTEM_TESTS_GCP_PROJECT configured in files/airflow-breeze-config/environment_variables.env, and a unique environment ID:

SYSTEM_TESTS_ENV_ID=<unique-id> \
BREEZE_INIT_COMMAND='export GOOGLE_CLOUD_PROJECT="${SYSTEM_TESTS_GCP_PROJECT}"' \
breeze testing system-tests \
  --forward-credentials \
  --test-timeout 2400 \
  providers/google/tests/system/google/cloud/vertex_ai/example_vertex_ai_agent_engine.py \
  -q

Latest result: 1 passed in 763.87s. The run exercised both synchronous and deferrable query jobs and completed resource teardown successfully.

The latest system test version builds its own agent container and creates its own query-output bucket. It still requires the one-time project setup documented in the system test docstring: enabling Cloud Build and Artifact Registry APIs, granting the Agent Engine service agent access to pull the image and write query output, and ensuring the Cloud Build service account can manage the test Artifact Registry repository.

Real GCP validation screenshots and per-operator logs are attached in the review thread.

---

Was generative AI tooling used to co-author this PR?

• Yes - Claude Code (Sonnet 4.6) and Codex (GPT-5)

Generated-by: Claude Code (Sonnet 4.6) and Codex (GPT-5) following the guidelines

[SameerMesiah97]

This is a large PR so I could only get through part of the diff in one sitting. I have left some comment for you to address.

[MaksYermak]

@AlejandroMorgante could you please provider a screenshot from Airflow UI that the new example_vertex_ai_agent_engine.py system test pass successfully?

[AlejandroMorgante]

@AlejandroMorgante could you please provider a screenshot from Airflow UI that the new example_vertex_ai_agent_engine.py system test pass successfully?

Sure. I validated the same operator lifecycle end-to-end in a real Airflow environment using this DAG:

AlejandroMorgante/agentic-airflow-demo@bedf76b

It exercises:

• CreateAgentEngineOperator
• GetAgentEngineOperator
• QueryAgentEngineOperator
• UpdateAgentEngineOperator
• DeleteAgentEngineOperator

All tasks completed successfully:

The DAG uses my real Agent Engine container, so the query payload is adapted to that runtime, but the operator lifecycle is the same as in example_vertex_ai_agent_engine.py.

[github-actions]

uv.lock on main just moved via #68642 ("Prepare provider documentation 2026-06-16"), commit 0236c57 and this PR currently conflicts.

Quickest fix:

git fetch upstream main && git rebase upstream/main
rm uv.lock && uv lock
git add uv.lock && git rebase --continue
git push --force-with-lease

Automated nudge — ignore if you're not ready to rebase. This comment is updated in place on future uv.lock bumps.

[SameerMesiah97]

I have left some more comments.

[SameerMesiah97]

Approved pending green CI.

[shahar1]

Almost there, last comments to handle from my prespective.
Please take a final look at all files to see that it's good to ship.