GCP - Agent Engine

I got Permission Denied, which identity is being used?

deploy an agent: user's identity
query an agent: user's identity
agent using model: agent's identity
agent calling third party services: use OAuth so the agent can perform tasks on your behalf.

What is Agent Identity?

Agent Identity is a feature that can be enabled by:

remote_app = agent_engines.create(
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY
    }
)

It will decide which identity would the agent use:

if use agent identity: each agent has its own identity (at the agent level)
- e.g. principal://agents.global.org-ORG_NUMBER.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/REASONING_ENGINE_ID
if do not use agent identity: use service agent (at the project level)
- e.g. principal://service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com

How to use agent identity to access 3rd-party services?

Agent identity can enable the agent to access third party services on your behalf by integrating with Secret Manager. User stores Client ID and Client Secret in Secret Manager, bind roles/secretmanager.secretAccessor to agent identity on the secret.

How is Agent Identity related to Context-Aware Access?

For the Vertex AI Agent Engine and Agent Identity, you can summarize it this way:

The Agent Identity provides the verifiable "who" (the principal).
Context-Aware Access (CAA) provides the verifiable "how" (the context). It requires the agent to prove its code is running in a trusted, verified runtime environment via mechanisms like mTLS (Mutual Transport Layer Security).
Opting out means the system stops checking the "how"—it ignores the requirement that the access attempt must originate from the trusted environment. The resource only checks the basic "who" (Does the principal exist and have the right role?).

How to fix the permission issues?

If you get PERMISSION DENIED when using Agent Identity, you need to grant permission for the agent to use the model or other services:

$ gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="roles/aiplatform-user"

Or grant permission to the principalSet://:

$ gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
  --role="ROLE_NAME"

To grant permission for ALL the agents under an org, use principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*