alloydb-agent-mode-quickstart

# AlloyDB Agent Pool Agents — from one pool to a swarm Enables an agent pool on an existing or newly created AlloyDB cluster, then deploys a running agent that answers questions against that read-only pool: either a single agent, or a swarm of parallel investigators with isolated per-session PostgreSQL scratch databases. The user does not need to write a config file by hand—ask for any missing settings and generate `./<name>.alloydb-agent.yaml` in the current working directory to drive the deployment scripts. ## Capabilities (pick one first) Ask which capability the user wants, then run only its steps: 1. **Provision an agent pool (Step P, `gcloud` + optional AlloyDB MCP, no config file):** enables agent mode on an existing AlloyDB cluster, or creates a new AlloyDB cluster with agent mode enabled, creates a dedicated VPC/subnet, and provisions an `AGENT_POOL` instance reachable over PSC. 2. **Simple agent (Steps 0–5):** deploys one agent (`<name>_agent`) querying the pool over MCP (`get_schema`, `execute_sql_read_only`) and optionally publishes it to Gemini Enterprise. 3. **Agent swarm (Steps 0–5):** deploys a worker agent with per-session scratch PostgreSQL databases (`agent_engine.agent.workspace: true`) plus a coordinator (`<name>_swarm_coordinator`, via `agent_engine.coordinator`) that fans questions across parallel worker sessions. **Key rules across capabilities:** - **Prerequisite pool:** Capabilities 2 and 3 require an AlloyDB agent pool in `READY`. Run capability 1 (Step P) first unless the user already has one. - **AlloyDB MCP tools vs. `gcloud`:** Where both this plugin's `alloydb-postgres` MCP server and `gcloud` work—such as inspecting existing clusters, instances, settings, or users (`list_clusters`, `get_cluster`, `list_instances`, `get_instance`, `list_pg_settings`, `list_users`), reusing configured `ALLOYDB_POSTGRES_*` settings after user confirmation, or loading small SQL schemas/data (`execute_sql`, `list_tables`) when the instance is network-reachable—prefer MCP when configured, and let the user know MCP is an option. Because MCP in the plugin may or may not be configured yet (or may not reach a PSC-only instance from outside its VPC), note briefly if MCP is unconfigured and fall back directly to `gcloud`. Agent Mode flags (`--enable-agent-mode`, `AGENT_POOL`, `agentPoolInfo.dnsName`), VPC/PSC networking, `--database-flags` updates, and Cloud Storage `clusters import` always require `gcloud`. - **Agent-managed config (`./<name>.alloydb-agent.yaml`):** Generate and maintain `./<name>.alloydb-agent.yaml` in the current working directory (alongside `./.venv`). Two orthogonal knobs under `agent_engine` control the deployed topology: 1. `agent.workspace: true | false` — controls whether Step 2 deploys the Cloud Run Agent Workspace (`alloydb-agent-workspace-<name>`) to give each session a private writable PostgreSQL scratch database. 2. `coordinator` (optional block) — controls whether Step 3 deploys the Swarm Coordinator (`<name>_swarm_coordinator`) and Step 5 registers the coordinator instead of the single agent in Gemini Enterprise. - **Upgrade in place or tear down:** A simple agent can enable scratch databases or a coordinator later by updating `./<name>.alloydb-agent.yaml` and re-running Steps 2–5. For updates and reverse-order teardown, see [references/updates_and_teardown.md](references/updates_and_teardown.md). Read it before deleting anything. To delete one deployment, run `deploy_agent.py teardown --config <config_path>`: it only lists what it would delete. Show that list, end your turn, and re-run with `--yes` only after the user confirms, even when they already asked for the teardown. **Working directory and `<skill>` path.** Run Steps 0–5 from a consistent working directory (where `bootstrap_env.sh` creates `./.venv`), replacing `<skill>` in commands below with the path to this skill directory. All cloud resources are namespaced by `<name>` so multiple deployments in one project never collide. ## Workflow (run in this order) Each step is a task node that provisions or verifies cloud resources. Follow these execution rules across the graph: - **Collect missing inputs before running commands:** Before running Step P or Step 0, check the required inputs for the chosen capability (listed in Step P or Step 1), ask the user for any missing settings directly in your chat reply, and **end your turn** to wait for their answer. If an interactive question tool is skipped or unavailable, ask in plain text—never invent resource names, passwords, or network settings. - **Explain the overall plan before creating cloud resources:** Once inputs are collected (before Step P or before Step 2), briefly tell the user what resources will be created and the expected total time (~15–30 min for an agent pool; ~8–15 min for a simple agent; ~12–20 min for an agent swarm). - **Before each step:** explain in plain language what the step is about to do and how long it typically takes (`Takes`) before running the command. - **After each step:** report what succeeded and the outputs needed by downstream steps (`AGENT_SA`, `AGENT_WORKSPACE_URL`, Agent Engine resource names). - **Never chain steps silently on failure:** verify each step's output before proceeding; stop and troubleshoot with the user on any error. ### P. Provision the AlloyDB agent pool (capability 1) > **Skip** if the user already has a `READY` agent pool. Put its cluster, pool > instance, and database into `database` in `./<name>.alloydb-agent.yaml` and > start at Step 0. **Goal:** Enable agent mode on the user's AlloyDB cluster and provision a dedicated VPC, subnet, service connection policy, and `AGENT_POOL` instance reachable over PSC. - **Input:** `<project_id>`, `<region>`, `<cluster>`, `<primary>` and its size, `<pool>`, `<vpc>`, `<subnet>`, and the initial `postgres` password (if new cluster) (collect in one message) - **Output:** a `READY` agent pool with `agentPoolInfo.dnsName`, plus the `project_id`, `region`, `vpc`, and `database` values for `./<name>.alloydb-agent.yaml` - **Takes:** ~15–30 min (prepare the network in parallel while agent mode provisions) **Prerequisites:** permissions to create AlloyDB clusters/instances, VPCs, and service connection policies in `<project_id>`. **Guidance:** Follow [references/agent_pool_setup.md](references/agent_pool_setup.md) step by step (using AlloyDB MCP tools when configured for inspection/SQL, and `gcloud` for agent-mode, PSC networking, and fallback operations), confirming each command's output before running the next. **Rules:** - Strict creation order: enable `dns.googleapis.com` → create VPC, subnet, and service connection policy → wait for cluster `agentModeInfo.state: ACTIVE` → create the `AGENT_POOL` instance. Out-of-order creation leaves the pool's private DNS zone unprovisioned. - At most one agent pool per cluster; deleting a pool blocks recreation on that cluster until backend cleanup finishes. Never delete a pool to retry without asking. - Use only the cluster the user names; never offer or change other clusters in the project. - Loading data (P.3) is optional; an empty `postgres` database is enough for pool setup and Step 4 (`deploy_agent.py validate`). ### 0. Environment initialization **Goal:** Verify local CLI prerequisites (`python3` 3.11+, `gcloud`, user auth, and ADC auth) and initialize `./.venv` in the working directory. - **Input:** current working directory - **Output:** `./.venv` with pinned runtime and deployment packages - **Takes:** ~1 min **Prerequisites:** required settings for Step 1 collected from the user (or from Step P); run from the working directory you will use for Steps 1–5. **Guidance:** Run `bootstrap_env.sh` once per working directory: ```bash "<skill>"/scripts/bootstrap_env.sh ``` **Rules:** - User credentials and ADC must both work before Step 1. If either fails, ask the user to run `gcloud auth login` or `gcloud auth application-default login`; never run them yourself (they need the user's browser). ### 1. Generate and validate the config **Goal:** Collect any missing settings from the user, generate `./<name>.alloydb-agent.yaml` in the current working directory from the template, and validate all fields and topology settings offline. - **Input:** user requirements and environment settings; writes `<config_path>` (`./<name>.alloydb-agent.yaml`) in the current working directory for Steps 2–5 and teardown - **Output:** `==> Topology: ...` and `==> Valid.`, or a list of errors to fix - **Takes:** seconds (offline check) **Prerequisites:** Step 0 passed. **Guidance:** 1. **Collect missing inputs in one message** (never guess environment names; if you just ran Step P, reuse its outputs without re-asking): - **Required from the user:** `<project_id>`, `<region>`, `database` (`cluster`, `instance` pool ID, `database` name), and `vpc` (`network`, `subnet`, and `network_attachment`—or offer defaults `agents-vpc`, `agents-subnet`, `agents-psc-attachment<name_suffix>`). - **Ask only if relevant or requested:** deployment `name` (otherwise derive `<db>-agent` or `<db>-swarm` with `_` replaced by `-`, lowercase alphanumeric and hyphens only, truncated to `<=24` chars), `name_suffix` (for shared foundation isolation), domain `context`, and `gemini_enterprise.app_id`. - **Auto-populate defaults:** derive `agent_engine.agent.display_name` (and `coordinator.display_name` when deploying a swarm) from `name`, set `agent_engine.agent.workspace` (`false` for simple agent, `true` for swarm), and include `agent_engine.coordinator` only when deploying a swarm. 2. **Write `./<name>.alloydb-agent.yaml`** in the current working directory (modeled on `"<skill>"/assets/example.alloydb-agent.yaml`) and run `validate_config.py`: ```bash .venv/bin/python "<skill>"/scripts/validate_config.py --config <config_path> ``` Check the printed topology line before continuing: - `agent_workspace=NO` vs. `agent_workspace=yes (per-session scratch databases)` reflects `agent_engine.agent.workspace`. - `coordinator=NO (single agent)` vs. `coordinator=yes (swarm coordinator)` reflects whether `agent_engine.coordinator` is present. **Rules:** - Do not proceed until validation exits `0`. Fix `<config_path>` directly—never edit generated Terraform or bundle files. - Show the user the validated `./<name>.alloydb-agent.yaml` and briefly explain what Steps 2–5 will provision and how long they take before starting Step 2. - `agent_engine.agent.display_name` must not contain `"Coordinator"`; `agent_engine.coordinator.display_name` (when set) should contain `"Coordinator"`. ### 2. Provision cloud infrastructure **Goal:** Provision the shared project networking/storage foundation, the per-deployment service account and AlloyDB IAM user, and (when `agent_engine.agent.workspace: true`) the Cloud Run Agent Workspace service. - **Input:** a validated `<config_path>` - **Output:** PSC network attachment, `AGENT_SA` (`agent-<name>@<project_id>.iam.gserviceaccount.com`), AlloyDB IAM user (`agent-<name>@<project_id>.iam`), and (when `workspace: true`) `AGENT_WORKSPACE_URL` for `alloydb-agent-workspace-<name>` - **Takes:** ~1–4 min warm; ~5–10 min on first run in a fresh project **Prerequisites:** Step 1 passed; permissions to enable APIs, manage IAM, and run Infrastructure Manager in `<project_id>`. **Guidance:** Run `deploy_infra.py` (idempotent): ```bash .venv/bin/python "<skill>"/scripts/deploy_infra.py --config <config_path> ``` It provisions two Infrastructure Manager stacks (creating only missing resources and leaving pre-existing ones untouched), plus the read-only `IAM_BASED` AlloyDB database user (`agent-<name>@<project_id>.iam`) on `database.cluster`: 1. **Shared foundation (`alloydb-agent-project<name_suffix>`):** APIs, VPC/subnet, PSC endpoint, private `*.run.app` DNS, network attachment, service-agent IAM, staging bucket, and Artifact Registry repo. 2. **Per-deployment stack (`alloydb-agent-<name>`):** `AGENT_SA` + IAM roles, and (when `agent_engine.agent.workspace: true`) the `alloydb-agent-workspace-<name>` Cloud Run service. **Rules:** - When `agent_engine.agent.workspace: true`, verify `isolation-self-check: PASS` in Cloud Run logs on first deploy (`gcloud run services logs read alloydb-agent-workspace-<name> --project=<project_id> --region=<region> --limit=50`). ### 3. Deploy to Agent Engine **Goal:** Package and deploy the ADK agent runtime(s) to Vertex AI Agent Engine with PSC egress and MCP toolsets wired. - **Input:** the validated `<config_path>` (auto-resolves the Agent Pool DNS name and, when `workspace: true`, the Cloud Run `AGENT_WORKSPACE_URL`) - **Output:** deployed Agent Engine resource name(s) (`projects/<project_id>/locations/<region>/reasoningEngines/<engine_id>`): `<name>_agent`, plus `<name>_swarm_coordinator` when `agent_engine.coordinator` is configured - **Takes:** ~5 min for a single agent; ~10 min when `coordinator` is also configured **Prerequisites:** Step 2 passed. **Guidance:** Run `deploy_agent.py deploy` (idempotent—updates existing engines for `<name>` in place): ```bash .venv/bin/python "<skill>"/scripts/deploy_agent.py deploy --config <config_path> ``` **Rules:** - Record the deployed Agent Engine resource name(s) in your step summary. ### 4. Validate the deployed agent **Goal:** Run a live validation turn against `<name>_agent` to verify end-to-end MCP connectivity and tool execution. - **Input:** `<config_path>` with Step 3 deployed - **Output:** `VALIDATE PASS: ...` (exit 0) or diagnostic failure (exit 1) - **Takes:** ~2 min **Prerequisites:** Step 3 passed. **Guidance:** Run `deploy_agent.py validate`: ```bash .venv/bin/python "<skill>"/scripts/deploy_agent.py validate --config <config_path> ``` If validation fails, consult [references/troubleshooting.md](references/troubleshooting.md). **Rules:** - Report the agent as working only after `deploy_agent.py validate` exits `0`