Agent
Agent
Deployable AI agent definition.
The agent runs on Agent Engine (Vertex AI Reasoning Engine). The engine pairs the manifest with an AgentDeploymentConfig to provision the ReasoningEngine, a service account with IAM bindings, and a staging bucket for source upload.
| Property | Type | Description |
|---|---|---|
| apiVersion | string | API schema version. Must be lowops.manifests.v1. |
| kind | string | Resource kind. Must be Agent. |
| metadata | map | The engine reads the reserved keys name and project to resolve the identity and the parent. |
| spec | Spec | Desired agent configuration. See Spec. |
Spec
User-authored agent specification.
Names the source build, the target Project, the platform, and the access grants of the agent.
| Property | Type | Description |
|---|---|---|
| description | string | Optional description. The engine does not use it to provision resources. The per-environment description comes from AgentDeploymentConfig. |
| target | string | Platform that runs the agent. Must be AGENT_ENGINE (Vertex AI Reasoning Engine), the only accepted value. |
| project | string | Name of the target Project manifest. Required. It sets the GCP project for the ReasoningEngine, the service account, and the IAM bindings. The project must exist in every environment of the parent OrganizationalUnit. |
| accessControl | AgentAccessControlConfig | Permissions that the service account of the agent gets over other platform resources: secrets, buckets, Pub/Sub topics, databases, and extra IAM roles. The plan validates the referenced resources. See AgentAccessControlConfig. |
| buildDefinition | string | Name of the BuildDefinition manifest (type: AGENT) that packages the agent as a versioned wheel. Required. The engine takes the publish ArtifactRegistry from agent.registry of the build. |
AgentAccessControlConfig
All external access rules of an AI agent.
Mirrors ApplicationAccessControlConfig, but agent rules can differ.
| Property | Type | Description |
|---|---|---|
| additionalRoles | list of string | Extra IAM roles for the agent service account, beyond the base roles (monitoring, logging, tracing, and aiplatform.user). |
| pubsub | ApplicationAccessControlPubsubConfig | Publish and subscribe grants for specific Pub/Sub topics. |
| buckets | list of ApplicationAccessControlBucketConfig | Cloud Storage buckets that the agent can read or write. |
| database | ApplicationAccessControlDatabaseConfig | PostgreSQL database access: instance and schema. |
| secrets | list of SecretsEntry | Map from Secret manifest name to how the agent gets the secret, typically as an environment variable. |
ApplicationAccessControlDatabaseConfig
PostgreSQL access for a workload.
Runs CREATE USER and GRANT on the target SQL instance.
| Property | Type | Description |
|---|---|---|
| name | string | Name of the Database manifest (an AlloyDB/PostgreSQL instance) that the application needs. |
| schema | string | Database (schema) in the instance that the application connects to. |
| privileges | list of string | SQL privileges for the application database role on the schema: USAGE, CREATE, or ALL. Each one becomes a GRANT statement. |
| readOnly | bool | If true, the application has read-only access, typically to a read replica. |
| extensions | list of string | PostgreSQL extensions to enable. Each entry runs CREATE EXTENSION IF NOT EXISTS. The engine merges the lists of all applications that share a schema. |
| secretSource | SecretSourceConfig | Source of the database credentials: the Secret manifest and how the application gets it (environment variable or file mount). Required. |
SecretsEntry
| Property | Type | Description |
|---|---|---|
| key | string | |
| value | SecretSourceConfig |
ApplicationAccessControlBucketConfig
Cloud Storage access for a workload.
Grants roles/storage.objectViewer or roles/storage.objectUser on a bucket.
| Property | Type | Description |
|---|---|---|
| name | string | Name of the Bucket manifest. It must exist in every environment of the parent ReleaseTrack. Required. |
| source | string | Name of a GithubRepository manifest whose contents seed the bucket through a gcloud storage rsync job in CI/CD. Optional. |
| permission | string | READ_ONLY grants roles/storage.objectViewer. WRITE grants roles/storage.objectUser. |
| mountPath | string | Absolute path in the container where Cloud Storage FUSE mounts the bucket. If omitted, the engine grants access but does not mount the bucket. |
| subPath | string | Bucket prefix that limits access, for example to mount one folder. If omitted, access covers the whole bucket. |
| promote | bool | If true, the engine promotes the bucket content through the ReleaseTrack with the application. |
| envVar | string | Environment variable that receives the bucket name, instead of a filesystem mount. Mutually exclusive with mount_path. |
ApplicationAccessControlPubsubConfig
Pub/Sub permissions for a workload.
The engine grants the roles to the service account of the workload.
| Property | Type | Description |
|---|---|---|
| publishTo | list of string | Names of PubSub manifests that the workload can publish to. Each entry grants roles/pubsub.publisher on the topic. |
| subscribeTo | list of string | Each entry, a PubSub manifest name, grants roles/pubsub.subscriber on the TOPIC. On a topic, this role only gives pubsub.topics.attachSubscription. The workload can attach a subscription, but it cannot pull from or acknowledge on any subscription, even a managed one in spec.subscriptions. To create a subscription, the workload also needs pubsub.subscriptions.create on the project, which this field does not grant. To consume from a managed subscription, use pull_from. The behavior stays unchanged for old manifests. |
| pullFrom | list of ApplicationAccessControlPubsubPullConfig | Each entry grants roles/pubsub.subscriber on one subscription from spec.subscriptions of a PubSub manifest, and nothing on the topic or the project. The topic and subscription must exist in the project of the workload, or validation fails. See ApplicationAccessControlPubsubPullConfig. |
ApplicationAccessControlPubsubPullConfig
Pub/Sub subscription that a workload consumes.
Grants roles/pubsub.subscriber on a subscription or its dead-letter subscription.
| Property | Type | Description |
|---|---|---|
| topic | string | Name of the PubSub manifest (topic) that declares the subscription. Required. |
| subscription | string | Name of the subscription in spec.subscriptions of that manifest. Required. |
| deadLetter | bool | If true, the grant targets the dead-letter subscription <topic>-<subscription>-dlq-sub. The subscription must declare deadLetter. To republish messages, the worker also needs the topic in publish_to. |
SecretSourceConfig
How to retrieve a secret and mount it into a workload.
The engine grants IAM access to the Secret Manager payload and resolves values JIT.
| Property | Type | Description |
|---|---|---|
| envVar | string | Name of the environment variable that holds the secret. Mutually exclusive with file_path: set exactly one. |
| version | string | Secret Manager version: latest or a number such as 1. Defaults to latest. |
Identity & Authentication
accessControl declares what the agent may reach inside GCP — databases, secrets, Pub/Sub. It is not the whole authentication story. One more thing happens automatically, without a manifest field, and one does not happen at all:
- Managed agent identity. On deploy, the engine provisions the agent's own runtime identity, grants it the specific IAM roles it needs (e.g. registry discovery, network egress), and proactively refreshes its access tokens. This is engine behavior, not something you configure per agent.
- 3-legged authorization for end-user actions is not done by the engine. If the agent's tools need to act as a specific person rather than as the agent itself — opening a pull request, for example — the agent's own code has to ask that person for consent, using Google's Agent Development Kit credential flow. The engine has no consent code and no manifest field controls it; it is a property of how the tool is written in the agent's source.
Full detail: Authentication, Managed by Default.
Best Practices
- Principle of Least Privilege: Declare only the permissions the agent needs.
USAGEis preferred overALLfor read-oriented agents. - No Implicit Inheritance: Agents do not inherit the CI/CD service account's permissions. Only what's declared in
accessControlis granted. - Per-Project Scoping: Agents operate within a single project boundary as defined in the manifest
spec.projectfield. TheaccessControlblock scopes all permissions to that project. - Secret Scoping: Agents can only access secrets explicitly listed in
accessControl.secrets. The engine injects secrets as environment variables at deployment time. - PubSub Directionality:
publishToandsubscribeToare separate fields. An agent that needs to read alerts should usesubscribeTo, notpublishTo. - Identity Is Automatic, Not a Field: You don't declare the agent's own runtime identity — see Identity & Authentication above.
Related Manifests
McpConfig— Governed MCP server deploymentAgentDeploymentConfig— Version pinning per environmentApplication— Standard application deployment (non-agent)Secret— Secrets referenced inaccessControl.secretsDatabase— Databases referenced inaccessControl.databasePubSub— Topics referenced inaccessControl.pubsub