Authenticate using an agent's own authority

Agents can access Google Cloud APIs and other resources by using their own authority. We recommend this method for agents hosted on Google Cloud to interact with other Google Cloud services.

When an agent acts on its own authority, it uses its primary SPIFFE identity to request Google Cloud access tokens.

Before you begin

Verify that you have chosen the correct authentication method.
Create and deploy an agent with Agent Identity enabled.
Verify that you have the roles required to complete this task.

Required roles

To get the permissions that you need to grant an agent access to Google Cloud services, ask your administrator to grant you the following IAM roles on the target resource:

To grant access to an agent:
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Security Admin (roles/iam.securityAdmin)
Recommended roles for the agent identity:
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Agent Default Access (roles/aiplatform.agentDefaultAccess)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
- Browser (roles/browser)
- Storage Object Viewer (roles/storage.objectViewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Grant access to agents

To let your agent access a Google Cloud service, you must grant the agent's identity the required roles on the target resource.

In IAM allow policies, agent identities use principal identifiers.

To grant an agent access to a resource, use the Google Cloud console or the gcloud CLI.

Console

In the Google Cloud console, go to the IAM page for the resource that you want to grant access to.
- For a project, go to the IAM page:
  Go to the IAM page
- For other resources, go to the page for that resource and click the Permissions or IAM tab.
Click Grant Access.
In the New principals field, enter the principal identifier that matches the level of access you want to grant:
- A single agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- All agents in a project: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- All agents in an organization: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
In the Select a role field, search for and select the role that you want to grant.
Click Save.

Google Cloud CLI

To grant an agent access to a resource, run the following command:

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Replace the following:

SERVICE: The Google Cloud service (for example, storage or bigquery).
RESOURCE_NAME: The name of the resource (for example, the bucket name or dataset ID).
PRINCIPAL_IDENTIFIER: The principal identifier that matches the level of access that you want to grant:
- A single agent: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- All agents in a project: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- All agents in an organization: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID: Your Google Cloud organization ID.