Agent

Deployable AI agent definition.

Declares the high-level intent for an AI agent hosted on Agent Engine (Vertex AI Reasoning Engine). Mirrors the Application manifest pattern but targets Agent Engine instead of Cloud Run, GKE, or Compute Engine; the engine pairs it with an AgentDeploymentConfig to provision the ReasoningEngine resource, the per-agent service account and its IAM bindings, and the staging bucket used for source upload.

Agentic Governance

The Agent manifest is a cornerstone of Infrastream's Agentic Governance framework. Every GCP permission an agent requires is declared here and visible in the PR diff — no implicit credential inheritance, no over-privileged service accounts. The agent's own runtime identity (IAM grants, token refresh) is provisioned automatically; see Identity & Authentication below.

Property	Type	Description
apiVersion	string	API schema version. Pins the manifest to a specific schema contract for backward-compatibility. Must be the constant `lowops.manifests.v1`.
kind	string	Resource kind discriminator. Identifies this document as an Agent so the engine routes it to the correct defaulter, validator, computer, and executor. Must be the constant `Agent`.
metadata	`map`	Classification labels and graph linkage. Free-form key/value pairs used to classify the manifest. Certain reserved keys (e.g. `name`, `project`) are read by the engine to resolve this manifest's identity and its parent in the dependency graph.
spec	Spec	Desired agent configuration. The authoritative, user-authored specification for this agent. See `Spec`.

Spec

User-authored agent specification.

Identifies the agent's source build, target Project and hosting platform, and the access-control grants applied to its service account. Mirrors ApplicationDefinition — the same build_definition/project/target model adapted for AI agents.

Property	Type	Description
description	string	Human-readable description of the agent. Optional free text describing the agent's role and purpose. Not read by the engine when provisioning resources (the per-environment description comes from `AgentDeploymentConfig`); it serves as documentation for the portal UI and as context for AI assistants reasoning about the manifest.
target	string	Target agent hosting platform. Selects where the agent runs; currently only `AGENT_ENGINE` is accepted (maps to Vertex AI Reasoning Engine) and this is enforced by schema validation. The executor always provisions Agent Engine, so the field acts as a forward-looking discriminator rather than a runtime switch.
project	string	Target Project manifest name. Required. Name of the `Project` manifest the agent deploys into, determining the GCP project where its ReasoningEngine, per-agent service account, and IAM bindings are provisioned. Validated to exist in every environment of the parent OrganizationalUnit.
accessControl	AgentAccessControlConfig	Agent access-control grants. Permissions the agent's service account receives over other platform resources — secrets, buckets, Pub/Sub topics, databases, and additional IAM roles. See `AgentAccessControlConfig`. Referenced dependencies are validated at plan time, and the `AgentDeploymentConfig` executor turns each grant into the corresponding IAM binding.
buildDefinition	string	Source build definition. Required. Name of the `BuildDefinition` manifest (`type: AGENT`) that packages this agent as a versioned wheel. Creates a dependency on that build; the agent computer resolves the publish `ArtifactRegistry` (from the build's `agent.registry`) and the package name to compose the deployable artifact reference for Agent Engine.

AgentAccessControlConfig

Aggregates all external access rules an AI agent requires.

Mirrors ApplicationAccessControlConfig but defined as a separate type to allow agent-specific access patterns to diverge independently. Agents deployed to Agent Engine (Vertex AI Reasoning Engine) may need different access semantics than containerized applications (e.g., no Redis volume mounts, no mesh-aware URLs).

Property	Type	Description
additionalRoles	list of string	Extra IAM roles for the agent service account. A list of additional IAM roles granted to the agent's service account beyond the base roles (monitoring, logging, tracing, and `aiplatform.user`).
pubsub	ApplicationAccessControlPubsubConfig	Pub/Sub publish and subscribe grants. The agent's permission to publish to or subscribe from specific Pub/Sub topics. See `ApplicationAccessControlPubsubConfig`.
buckets	list of ApplicationAccessControlBucketConfig	Cloud Storage bucket access rules. A list of bucket access rules describing which Cloud Storage buckets the agent may read from or write to. See `ApplicationAccessControlBucketConfig`.
database	ApplicationAccessControlDatabaseConfig	PostgreSQL database access. The agent's access to a specific PostgreSQL database instance and schema. See `ApplicationAccessControlDatabaseConfig`.
secrets	list of SecretsEntry	Secrets consumed by the agent. A map from `Secret` manifest name to the configuration describing how that secret is exposed to the agent (typically as an environment variable). See `SecretSourceConfig`.

Identity & Authentication

accessControl declares what the agent may reach inside GCP — databases, secrets, Pub/Sub. It is not the whole authentication story. Two more things happen automatically, without additional manifest fields:

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. If the agent's tools (via the underlying Agent Development Kit runtime) need to act as a specific person rather than as the agent itself — opening a pull request, for example — the runtime requests that person's consent at the moment of the action. No manifest field controls this today; it's a property of how the tool is implemented in the agent's source, not the deployment manifest.

Full detail: Authentication, Managed by Default.

Best Practices

Principle of Least Privilege: Declare only the permissions the agent needs. SELECT is preferred over ALL for read-oriented agents.
No Implicit Inheritance: Agents do not inherit the CI/CD service account's permissions. Only what's declared in accessControl is granted.
Per-Project Scoping: Agents operate within a single project boundary as defined in the manifest spec.project field. The accessControl block 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: publishTo and subscribeTo are separate fields. An agent that needs to read alerts should use subscribeTo, not publishTo.
Identity Is Automatic, Not a Field: You don't declare the agent's own runtime identity — see Identity & Authentication above.

ApplicationAccessControlDatabaseConfig

Configures PostgreSQL interaction permissions for a workload.

Executes dynamic DDL (CREATE USER, GRANT) against the target SQL instance using an administrative proxy, setting up specific schema rights.

Property	Type	Description
name	string	Target Database manifest name. The name of the `Database` manifest this application requires access to. Resolves to a concrete AlloyDB/PostgreSQL instance during computation.
schema	string	Database schema to connect to. The specific database (schema) within the instance the application connects to. Feeds the computed schema and per-deployment access grants used by the Database executor to provision users, roles, and grants.
privileges	list of string	SQL privileges to grant on the schema. A list of SQL privileges granted to the application's database role on the target schema. Each entry (one of `USAGE`, `CREATE`, `ALL`) translates into `GRANT` statements executed against the PostgreSQL instance.
readOnly	bool	Connect against a read replica. When true, the application is wired for read-only access, typically to connect to a read replica rather than the primary instance.
extensions	list of string	PostgreSQL extensions to enable. A list of PostgreSQL extensions to enable in the target database for this application. Each entry runs `CREATE EXTENSION IF NOT EXISTS`; extensions are merged across all applications sharing a schema in the computed database schema.
secretSource	SecretSourceConfig	Credential source for the database. Required. Defines how the application obtains its database credentials, e.g. from which `Secret` manifest and how it is exposed (environment variable or file mount). See `SecretSourceConfig`.

ApplicationAccessControlPubsubConfig

Configures Pub/Sub interaction permissions for a workload.

Translates to roles/pubsub.publisher and roles/pubsub.subscriber IAM bindings assigned to the application's underlying service account.

Property	Type	Description
publishTo	list of string	Topics the workload may publish to. A list of `PubSub` manifest names this workload is allowed to publish messages to. Each entry grants `roles/pubsub.publisher` to the workload's service account on the corresponding topic.
subscribeTo	list of string	Topics the workload may subscribe to. A list of `PubSub` manifest names this workload is allowed to create subscriptions for and pull messages from. Each entry grants `roles/pubsub.subscriber` to the workload's service account on the corresponding topic.

ApplicationAccessControlBucketConfig

Configures Google Cloud Storage interaction permissions for a workload.

Translates to roles/storage.objectViewer or roles/storage.objectUser IAM bindings assigned to the application's service account, and can map specific paths.

Property	Type	Description
name	string	Target Bucket manifest name. Required. The name of the `Bucket` manifest this application requires access to. The bucket must exist in every environment defined by the parent `ReleaseTrack`.
source	string	Source repository to sync into the bucket. Optional reference to a `GithubRepository` manifest whose contents seed the bucket. The CI/CD system uses this to set up a `gcloud storage rsync` job that mirrors the repository data into the bucket.
permission	string	Access level granted on the bucket. The permission level for this bucket: `READ_ONLY` grants `roles/storage.objectViewer`, and `WRITE` grants `roles/storage.objectUser` to the application's service account on the bucket.
mountPath	string	In-container mount path for the bucket. The absolute path at which the bucket is mounted (via Cloud Storage FUSE) inside the container. When omitted, permissions are still granted but the bucket is not mounted as a filesystem.
subPath	string	Restrict access to a bucket sub-path. A sub-path (prefix) within the bucket that access is scoped to; when omitted, access covers the whole bucket. Commonly used to mount a specific folder of the bucket into the container.
promote	bool	Promote bucket contents with the release. When true, the bucket's content is promoted through the `ReleaseTrack` alongside the application, typically for shipping generic application configuration data with each release.
envVar	string	Environment variable to receive the bucket name. The name of an environment variable populated with the resolved bucket name, giving the application the bucket name as plain configuration instead of a filesystem mount. Mutually exclusive with `mount_path`.

SecretsEntry

Property	Type	Description
key	string
value	SecretSourceConfig

SecretSourceConfig

Defines how a secret should be retrieved and mounted into a workload.

Triggers IAM bindings for Secret Manager payload access. Values are resolved JIT and passed into the container via environment variables or file mounts.

Property	Type	Description
envVar	string	Environment variable name for the secret. The name of the environment variable populated with the secret's value. Mutually exclusive with `file_path`: set exactly one to choose environment-variable versus file-mount delivery.
version	string	Secret Manager version to resolve. The specific version of the secret to retrieve from the backend, either `latest` or a numeric version like `1`. When omitted, `latest` is assumed.

McpConfig — Governed MCP server deployment
AgentDeploymentConfig — Version pinning per environment
Application — Standard application deployment (non-agent)
Secret — Secrets referenced in accessControl.secrets
Database — Databases referenced in accessControl.database
PubSub — Topics referenced in accessControl.pubsub

Agent​

Spec​

AgentAccessControlConfig​

Identity & Authentication​

Best Practices​

ApplicationAccessControlDatabaseConfig​

ApplicationAccessControlPubsubConfig​

ApplicationAccessControlBucketConfig​

SecretsEntry​

SecretSourceConfig​

Related Manifests​