---
title: "Vertex Agents"
slug: vertex-agents
section: Governance & Operations
status: stable
description: "The `vertex-agents` repository is the single home for the Alliance Abroad agent fleet: 23 registered agents, both Vertex AI Agent Engine agents and Cloud Run services, governed by one registry file and one runtime scope guard."
last-updated: 2026-10-07
---

# Vertex Agents

The `vertex-agents` repository is the single home for the Alliance Abroad agent fleet: 23 registered agents, both Vertex AI Agent Engine agents and Cloud Run services, governed by one registry file and one runtime scope guard. [1] [2]

## Overview

Every agent has a directory at the repo root, an entry in `registry.toml`, and (for Cloud Run agents) a GitHub Actions deploy workflow that rebuilds the service when the agent directory, `shared/**` or `registry.toml` changes. [1] [7] [15] All agents authenticate with GCP Application Default Credentials and reach GitHub, Asana and Teams through the Alliance MCP Gateway using a per-agent robot identity, not through credentials held in the agent. [2]

This page is the catalog: what each agent is for, how it is triggered, where it runs, and what it may do about tickets. The Terraform-managed GCP inventory for the projects these agents run in lives on the [GCP Vertex environment page](/docs/gcp-env-vertex). [28] The two agents that review and document pull requests have their own pages: [PR Review Agents](/docs/pr-review-agents) and [Docs Update Agent](/docs/docs-update-agent). [29] [30]

> **Code-verified baseline**
>
> Read against `main` of `vertex-agents` at commit `d1c8408` (2026-10-02); the two promotion-agent rows were updated on 2026-10-06 for vertex-agents #285. The registry is the source of truth for purpose, trigger and allowed environments; deploy workflows are the source for the runtime project. The generated `AGENTS.md` table lags the registry in places. [1] [3]

## Repo Boundary and Registry

New agents are created in `vertex-agents` only, never in `gcp-connector`. The full agent fleet was migrated here from `gcp-connector` on 2026-09-08, and the rule was written down by the registry cleanup PR. [2] [6] No agent receives a carve-out from the registry; the earlier "standing exception" for the two promotion agents was reversed the same day. [2]

| Field in `registry.toml` | Meaning |
| --- | --- |
| `id`, `name`, `description`, `directory` | Identity and what the agent does |
| `trigger` | What fires it |
| `allowed_environments` | Exhaustive list of environments it may run in; an empty list pauses the agent |
| `repos` | GitHub repos that embed or trigger the agent |
| `engine_id`, `vertex_engine_required` | Agent Engine resource id, or `false` for Cloud Run services |
| `owner` | Responsible GitHub login |

Source: [1]

Adding an agent means creating the directory with `agent.py`, `requirements.txt` and `README.md`, adding the registry entry, updating the README tables, wiring a trigger, and making sure `shared/` is in the container build context. [2]

## Agent Catalog

Runtime projects below come from each agent's deploy workflow or Cloud Build config. Two GCP projects appear: `alliance-platform-agents` (direct Cloud Run deploys) and `skilled-script-469819-f2` (Cloud Build deploys and the Vertex AI engines). [7] [15] [16] Environments are the registry `allowed_environments` values, enforced at runtime by the scope guard. [1]

### Scheduled and Webhook Agents

| Agent | Purpose | Trigger | Runtime project | Environments |
| --- | --- | --- | --- | --- |
| `security-agent` | GCP security posture checks (IAM, Cloud SQL, Cloud Run, secrets, buckets, firewall, org policy, KMS, GKE), posts findings to Platform Pulse, auto-remediates what it can [1] | Cloud Scheduler, every 6 hours [1] | `alliance-platform-agents` [7] | development, qa, production |
| `branch-drift-agent` | Detects merges that bypass the dev-first workflow, opens and merges backport PRs, runs a report-only branch audit [1] | Cloud Scheduler, `POST /run` [1] | `alliance-platform-agents` [8] | development, qa, production |
| `env-audit-agent` | Audits dev, QA and prod for ingress cross-contamination, webhook URL bleed, Cloud SQL SSL and DNS drift [1] | n8n workflow every 24 hours, `POST /run` [1] | `alliance-platform-agents` [9] | development, qa, production |
| `pr-hygiene-agent` | Open-PR digest, escalating nags at 7, 14 and 21 days, dependabot patch and minor auto-merge after local verification, auto-close of abandoned PRs [1] | n8n daily schedule, `POST /run` [1] | `alliance-platform-agents` [10] | development, qa, production |
| `vertex-sync-agent` | Compares `registry.toml` with deployed Agent Engine resources and reports `IN_SYNC`, `CONFIG_DRIFT`, `REGISTERED_NOT_DEPLOYED` or `DEPLOYED_NOT_REGISTERED` [1] | n8n workflow every 60 minutes, `POST /run` [1] | `alliance-platform-agents` [13] | development |
| `gke-workload-health-agent` | Pod health signals, CPU and memory utilization, Postgres connection-pool usage and stuck managed certificates; returns a JSON summary for n8n to post [1] | n8n schedule, `POST /run` (hourly) [1] | `skilled-script-469819-f2` [17] | development, qa, production |
| `secrets-drift-agent` | Diffs n8n credentials and a configured set of Secret Manager secrets against the previous snapshot; reads metadata only, never secret payloads [1] | n8n hourly schedule, `POST /run` [1] | `skilled-script-469819-f2` [19] | development |
| `bug-diagnosis-agent` | Cloud Run webhook receiver for the IT Requests Portal Asana intake project; keeps only Bug-category tasks, dedupes in Firestore, dispatches to the reasoner and posts the verdict as an Asana comment [1] | Asana webhook, `POST /webhook/asana` [1] | `skilled-script-469819-f2` [2] | development |
| `pr-review-eligibility-agent` | Decides whether a PR is eligible for AI review and dispatches `pr-review-agent` [1] | GitHub App webhook, `POST /webhook/github` [1] | `skilled-script-469819-f2` [16] | development |
| `docs-update-agent` | Proposes citation-backed Nexus doc edits after a PR merges [1] | `POST /process-pr`, sweep and drift schedules [1] | `skilled-script-469819-f2` [15] | development |

### On-Demand, Promotion and Utility Agents

| Agent | Purpose | Trigger | Runtime project | Environments |
| --- | --- | --- | --- | --- |
| `dev-to-qa-sync-agent` | Dispatches the release workflow at a `release/*` branch for the sandbox-model repos (BackOfficePrototype: `deploy-release-qa.yml`, kind `release_dispatch` since vertex-agents #285 on 2026-10-06) and promotes development to qa by PR merge for n8n-workflows, the only `promote` repo left — an unscoped run covers n8n-workflows only; waits for the QA deploy, runs a health check, posts two Teams summaries [1] | Manual, `POST /run`; no scheduler wired in the registry [1] | `alliance-platform-agents` [11] | development |
| `qa-to-prod-sync-agent` | Promotes qa to production with a pre-flight divergence guard, waits for the prod deploy and health-checks it; manual by design and never scheduled. Since vertex-agents #285 (2026-10-06) its default promotion list is empty — `/run` returns `{"status":"no_repos"}` — and it stays deployed only as the backing service for the `deploy-prod` skill [1] | Manual, `POST /run` [1] | `alliance-platform-agents` [12] | production |
| `user-addition-agent` | Watches four identity surfaces (GCP IAM, GitHub org membership, Azure and Entra audit logs, Google Workspace) and alerts on new members [1] | Manual, `POST /run` [1] | `skilled-script-469819-f2` [18] | development |
| `openstatus-alert-agent` | Polls the self-hosted OpenStatus instance and alerts on a status transition after two consecutive non-active polls [1] | Manual, `POST /run` [1] | `skilled-script-469819-f2` [20] | development |
| `pr-latency-agent` | Daily digest of BackOfficePrototype PR merge-latency KPIs plus CI build-time tracking for six repos; read-only, always posts fresh [1] | Manual, `POST /run` [1] | `skilled-script-469819-f2` [21] | development |

Promotion agent notes. `dev-to-qa-sync-agent` refuses to run with a `409 qa_frozen` response when the IT Request Portal reports an active QA freeze window, and fails closed if the portal cannot be reached. [26] The `qa-to-prod-sync-agent` default promotion list includes HostPortalPrototype as of PR 245, although the registry `repos` array still lists three repositories. [25] [1]

### Vertex AI Agent Engine Agents

| Agent | Purpose | Trigger | Environments |
| --- | --- | --- | --- |
| `pr-review-agent` | Runs the Gate 0 to Gate 7 review of a PR and returns a structured verdict; no merge capability in any mode [1] | Synchronous call from `pr-review-eligibility-agent` [1] | development |
| `bug-diagnosis-reasoner` | Multi-turn Gemini function-calling agent that diagnoses Bug-category submissions against the matching GitHub repo and returns a verdict with competing hypotheses and an evidence ledger [1] | Synchronous call from `bug-diagnosis-agent` [1] | development |

Agent Engine agents are deployed with `deploy.py`, which updates the existing engine in place by default so the registry `engine_id` stays valid; a forced new engine requires manually propagating the new id. [22] Each Engine bundles `registry.toml` at deploy time, so a registry change reaches a running engine only after a redeploy. [1]

### Paused and Dormant Agents

| Agent | State |
| --- | --- |
| `qa-agent` | Paused: `allowed_environments` is empty (paused 2026-08-04) [1] |
| `iac-sync-agent` | Paused: `allowed_environments` is empty (paused 2026-08-04) [1] |
| `posthog-agent` | Trigger disabled since 2026-08-06; the service stays deployed in a standing-order-compliant state [1] [14] |
| `n8n-sync-agent` | Dormant: no live trigger [1] |
| `n8n-upstream-sync-agent` | Dormant: no live trigger [1] |
| `standup-digest-agent` | Dormant: no live trigger (the Manus scheduled task it relied on is retired) [1] |

### Not in the Registry

Two infrastructure utilities, `github-token-minter` and `cloudbuild-teams-notifier`, live in the repo but deliberately have no registry entry or scope guard because they are not monitoring agents and ship no `agent.py`. [2] The `db-query-proxy` directory is a plain read-only HTTP query proxy in front of the QA and prod Cloud SQL instances; the repo README describes it as not part of the agent family, and it has no registry entry. [27] [1] A `db-query-proxy-token-broker` directory also exists at the repo root. [2]

## Ticket-Creation Policy

The policy has changed twice; the code today is the authority.

1. **Ban (2026-08-04).** A standing order made all Vertex agents cease creating tickets and paused them. PR 57 removed ticket-creation code and set `allowed_environments = []` for `pr-review-agent`, `qa-agent`, `volume-testing-agent`, `overseer-agent` and `iac-sync-agent`. [5]
2. **Scoped reversal (2026-09-08 to 2026-09-09).** Ticket creation was re-enabled for specific agents where findings warrant tracked follow-up. The shared helper `create_ticket_if_new` searches the open tasks of the New Intake section of the Platform Pulse Asana project for an exact title match and creates a ticket only if none exists, so re-running a check never duplicates a ticket. The title is therefore the dedup key and must be stable for a given finding. [4]
3. **Agents that reference the helper today:** `env-audit-agent`, `user-addition-agent`, `branch-drift-agent`, `pr-hygiene-agent`, `security-agent` and `gke-workload-health-agent`, per a code search of the repo. [4] The re-enable PRs for `env-audit-agent`, `user-addition-agent`, `branch-drift-agent`, `security-agent` and `gke-workload-health-agent` are PR 117 to PR 121. [31] [32] [33] [34] [35]
4. **One scoped exception inside a reviewer.** `pr-review-agent` files one advisory god-file ticket per file in the Platform Pulse intake project, deduplicated by the title `[God File] repo/path`. [23] See [PR Review Agents](/docs/pr-review-agents). [30]
5. **Audit records, not work items.** `pr-review-eligibility-agent` creates an already-completed "merge record" task in the "Completed (DoD)" section of the Platform Pulse project when a reviewed PR lands, through the gateway under an Asana-scoped robot role that can only create and update tasks. [24]

All other agents report through Platform Pulse only. The Asana helper calls Asana directly with the platform bot's personal access token rather than through the gateway, because the gateway's Asana backend has no working shared-credential fallback for robot identities. [4]

## Scope Guard and CI

`shared/scope_guard.py` is the runtime guard. Batch agents call `check_scope` at startup; long-running HTTP services call `is_scope_permitted` once and gate each route, because `check_scope` exits the process on a denied scope. If `shared/` is missing from the image the agent refuses to run (fail closed). [2]

CI validates the registry on every push and pull request (`enforce-agent-scope.yml`), and `AGENTS.md` is regenerated from the registry by the `registry-drift` workflow. [1] [3] Each agent has its own `deploy-*.yml` workflow triggered by changes to its directory, `shared/**` or `registry.toml`. [7] [15]

## Decommissioned Agents

| Agent | Decommissioned | Notes |
| --- | --- | --- |
| Original `pr-review-agent` ("Vertex Reviewer") | 2026-08-07 | Replaced on 2026-08-13 by a from-scratch rebuild under the same id; the new one is CI-gated and has no merge capability [1] |
| `overseer-agent` and `observer-agent-v2` | 2026-08-11 | Overseer had been silently non-functional since mid-July; the watchdog was removed with it [1] [2] |
| `asana-hygiene-agent` | 2026-08-12 | Former `gcp-connector` agent; only a stale comment was removed from the registry [6] |
| `volume-testing-agent` | 2026-08-26 | Both volume-testing systems retired at the owner's request [1] |
| `ci-failure-alert-agent` | 2026-09-09 | Removed with its deploy workflow and the three GitHub App webhooks that fed it [1] |

The registry records that the live Cloud Run services and Cloud Scheduler jobs for `overseer-agent` and `volume-testing-agent` could not be deleted from the repo because the gateway's GCP credential was read-only at the time; verify against the live inventory before assuming they are gone. [1]

## Known Gaps

- The registry descriptions for `security-agent`, `branch-drift-agent` and `env-audit-agent` still say "Does not file Asana tickets", while the code references the ticket helper. [1] [4]
- `AGENTS.md` omits `branching-sandbox` from the `pr-review-agent` repo list and lists 12 repos for the eligibility agent where the registry lists 14. [3] [1]
- Registry triggers for `dev-to-qa-sync-agent` and `pr-latency-agent` say no scheduler is wired. Confirm in the live scheduler inventory before documenting a schedule. [1]

## References

[1]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/registry.toml "vertex-agents registry.toml"
[2]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/README.md "vertex-agents README"
[3]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/AGENTS.md "vertex-agents AGENTS.md (generated scope matrix)"
[4]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/shared/asana_ticket.py "shared/asana_ticket.py"
[5]: https://github.com/Alliance-Strategies/vertex-agents/pull/57 "PR 57: cease ticket creation and pause affected Vertex agents"
[6]: https://github.com/Alliance-Strategies/vertex-agents/pull/114 "PR 114: registry cleanup and no-new-agents-in-gcp-connector rule"
[7]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-security-agent.yml "deploy-security-agent.yml"
[8]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-branch-drift-agent.yml "deploy-branch-drift-agent.yml"
[9]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-env-audit-agent.yml "deploy-env-audit-agent.yml"
[10]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-pr-hygiene-agent.yml "deploy-pr-hygiene-agent.yml"
[11]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-dev-to-qa-sync-agent.yml "deploy-dev-to-qa-sync-agent.yml"
[12]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-qa-to-prod-sync-agent.yml "deploy-qa-to-prod-sync-agent.yml"
[13]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-vertex-sync-agent.yml "deploy-vertex-sync-agent.yml"
[14]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-posthog-agent.yml "deploy-posthog-agent.yml"
[15]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-docs-update-agent.yml "deploy-docs-update-agent.yml"
[16]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/pr-review-eligibility-agent/cloudbuild.yaml "pr-review-eligibility-agent cloudbuild.yaml"
[17]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-gke-workload-health-agent.yml "deploy-gke-workload-health-agent.yml"
[18]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-user-addition-agent.yml "deploy-user-addition-agent.yml"
[19]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-secrets-drift-agent.yml "deploy-secrets-drift-agent.yml"
[20]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-openstatus-alert-agent.yml "deploy-openstatus-alert-agent.yml"
[21]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-pr-latency-agent.yml "deploy-pr-latency-agent.yml"
[22]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/.github/workflows/deploy-pr-review-agent.yml "deploy-pr-review-agent.yml"
[23]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/shared/asana_god_file_ticket.py "shared/asana_god_file_ticket.py"
[24]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/shared/asana_merge_record.py "shared/asana_merge_record.py"
[25]: https://github.com/Alliance-Strategies/vertex-agents/pull/245 "PR 245: qa-to-prod-sync-agent adds HostPortalPrototype"
[26]: https://github.com/Alliance-Strategies/vertex-agents/pull/138 "PR 138: check QA freeze window before promoting dev to qa"
[27]: https://github.com/Alliance-Strategies/vertex-agents/blob/main/db-query-proxy/README.md "db-query-proxy README"
[28]: /docs/gcp-env-vertex "GCP Vertex environment"
[29]: /docs/docs-update-agent "Docs Update Agent"
[30]: /docs/pr-review-agents "PR Review Agents"
[31]: https://github.com/Alliance-Strategies/vertex-agents/pull/117 "PR 117: env-audit-agent re-enable ticket creation"
[32]: https://github.com/Alliance-Strategies/vertex-agents/pull/118 "PR 118: user-addition-agent ticket creation with dedup"
[33]: https://github.com/Alliance-Strategies/vertex-agents/pull/119 "PR 119: branch-drift-agent re-enable ticket creation"
[34]: https://github.com/Alliance-Strategies/vertex-agents/pull/120 "PR 120: security-agent re-enable ticket creation"
[35]: https://github.com/Alliance-Strategies/vertex-agents/pull/121 "PR 121: gke-workload-health-agent re-enable ticket creation"