Configura i criteri dell'agente IAM

Puoi creare policy di autorizzazione IAM (Identity and Access Management) per gestire la comunicazione degli agenti con le risorse registrate in Agent Registry. Agent Gateway utilizza Identity-Aware Proxy (IAP) per applicare le policy.

La pagina Policy nella console Cloud de Confiance consente di creare policy di autorizzazione IAM.

Google Cloud CLI e Terraform supportano la creazione di policy in uscita IAM.

Puoi anche creare Unified Access Policies (UAP) IAM, che possono contenere regole con effetti di autorizzazione e di negazione.

Prima di iniziare

Prima di creare una policy di autorizzazione IAM:

  1. Configurare un progetto di fatturazione Cloud de Confiance .

  2. Abilita l'API Identity-Aware Proxy (iap.googleapis.com) nel tuo progetto. Il gateway utilizza l'API Identity-Aware Proxy per autenticare e autorizzare il traffico in uscita dai tuoi agenti.

  3. Conoscere l'identità dell'agente di cui vuoi gestire l'accesso da. Per gestire l'accesso da un intero registry utilizzando la console Cloud de Confiance , seleziona il progetto che contiene il registry.

    • Agent Platform e agenti Gemini Enterprise: conosci l'identità dell'agente.

    • Agenti fai da te (Cloud Run): conosci l'identità basata sul account di servizio.

  4. Le risorse dell'agente di destinazione (agenti, server MCP ed endpoint) per cui vuoi gestire l'accesso devono essere registrate in Agent Registry.

    La convalida della risorsa di destinazione avviene quando la policy è associata alla risorsa, non in fase di runtime. Non puoi associare una policy a una risorsa non registrata. Il tentativo di creare un'associazione di policy per una risorsa non registrata non va a buon fine immediatamente e restituisce l'errore "Entità richiesta non trovata" (NOT_FOUND).

    Ti consigliamo di definire e applicare le policy in una pipeline di integrazione continua e deployment continuo (CI/CD). In questo modo, i riferimenti non validi o gli errori di battitura vengono rilevati durante i controlli di integrazione prima del deployment.

  5. Configura un Agent Gateway. Ti consigliamo di configurare inizialmente Agent Gateway in modalità dry run. Per scoprire di più su Agent Gateway, consulta la panoramica di Agent Gateway.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare Agent Platform per gli agenti AI, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Crea una policy di autorizzazione IAM utilizzando IAP

Puoi definire policy in uscita per i seguenti tipi di interazioni degli agenti:

Crea una policy da agente a registry

Una policy da agente a registry consente al tuo agente di accedere a tutti gli agenti, i server MCP e gli endpoint nel registry degli agenti nel progetto corrente.

Console

Cloud de Confiance , segui questi passaggi:

  1. Seleziona l'agente di origine e il registry di destinazione.

    1. Nella console Cloud de Confiance , vai alla pagina Policy:

      Vai a Policy

    2. Per aggiungere un criterio di accesso uniforme IAM per il traffico in uscita di Agent Gateway, fai clic su Aggiungi policy IAM.
    3. Per selezionare gli agenti di origine, segui questi passaggi:
      1. Per selezionare tutti gli agenti nel registry degli agenti che si trovano nel progetto attualmente selezionato, seleziona Tutti gli agenti.
      2. Per selezionare un agente specifico nel progetto attuale, segui questi passaggi:
        1. Seleziona Agente individuale. Per trovare l'agente, cercalo utilizzando il campo Filtra .
        2. Seleziona l'agente di origine a cui vuoi concedere l'accesso.
        3. Per selezionare l'agente, fai clic su Ok.
    4. In Destinazione di accesso, fai clic su Registry.
    5. Per creare la policy di autorizzazione IAM e associarla al registry, fai clic su Crea.
  2. Per creare una condizione, segui questi passaggi: In Condizioni, fai clic su Aggiungi condizione. Nella finestra di dialogo Aggiungi condizione, procedi nel seguente modo:
    1. In Titolo, inserisci il nome della condizione.
    2. In Descrizione, inserisci la descrizione della condizione.
    3. Per aggiungere una condizione utilizzando il Generatore di condizioni, segui questi passaggi:
      1. In Tipo di condizione, seleziona il tipo di condizione tra i seguenti:
        1. Nome: l'accesso dell'agente è limitato in base al nome della risorsa a cui viene eseguito l'accesso.
        2. ReadOnly: indica se l'accesso dell'agente è limitato alla lettura dei dati, il che impedisce le operazioni di scrittura da parte dell'agente.
        3. Distruttivo: indica se gli agenti possono eseguire azioni considerate dannose o irreversibili, come l'eliminazione di risorse.
        4. Idempotente: indica se l'accesso dell'agente può essere sostituito.
        5. Open world: se l'agente può interagire con un "open world" di entità esterne (ad esempio, uno strumento di ricerca web). Se imposti questa condizione su "false", l'interazione con l'agente viene considerata chiusa.
      2. In Operatore, seleziona l'operatore booleano.
      3. In Valore, seleziona il valore per la condizione.
    4. Per aggiungere un'altra condizione, fai clic su Aggiungi un'altra condizione.
    5. Per salvare la condizione, fai clic su Salva.

gcloud

Per creare una policy in uscita da agente a registry utilizzando gcloud CLI, segui questi passaggi:

  1. Crea la policy IAP che contiene la policy IAM.

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPALS"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}

    Sostituisci quanto segue:

    • AGENT_PRINCIPALS: un array di entità per le identità degli agenti di origine. Le entità possono essere un array di una o più entità singole (principal://...) o set di entità (principalSet://...), formattati come segue:
      • Identità degli agenti integrate (Agent Runtime, Gemini Enterprise o Cloud Run con identità dell'agente): principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER, ad esempio:
        • Agent Runtime (Reasoning Engine): principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-agent
        • Gemini Enterprise (Discovery Engine): principal://agents.global.org-123456789012.system.id.goog/resources/discoveryengine/projects/9876543210/locations/global/engines/my-engine/assistants/default_assistant/agents/default/core_assistant
        • Cloud Run (identità agente): principal://agents.global.org-123456789012.system.id.goog/resources/run/projects/9876543210/locations/us-central1/services/my-cloud-run-agent
      • Federazione delle identità per i workload (agenti personalizzati o esterni): principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT, ad esempio principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
    • CONDITION:

      Il parametro della condizione, formattato come segue:

      "condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}

      Sostituisci quanto segue:

      • CONDITION_TITLE: il titolo della condizione
      • CONDITION_DESCRIPTION: la descrizione della condizione
      • CEL_EXPRESSION: l'espressione condizionale. Questa espressione deve essere un'espressione CEL valida. Per consentire l'accesso, deve essere valutata come true.

  2. Imposta la policy di autorizzazione IAM in IAP per tutte le risorse in Agent Registry:

    gcloud iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=agent-registry \
    --region=REGION

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto del progetto che contiene la risorsa. In alternativa, puoi associare la policy a una cartella o a un'organizzazione specificando rispettivamente i flag --folder o --organization.
    • REGION: la regione in cui si trova la risorsa

    L'esempio seguente mostra l'accesso in uscita per una gerarchia di agenti:

    {
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/1234"
      ]
    }
  ]
}
}

Terraform

Per concedere l'accesso in uscita a tutte le risorse in un'istanza di Agent Registry, configura la risorsa google_iap_agent_registry_iam_member nel progetto che ospita il registry e l'Agent Gateway:

resource "google_iap_agent_registry_iam_member" "registry_egress" {
project  = "PROJECT_ID"
location = "REGION"
role     = "roles/iap.egressor"
member   = "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER"
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che ospita il registro degli agenti e l'Agent Gateway
  • REGION: la località del registry (ad esempio, us-central1 o global)
  • ORGANIZATION_ID: ID organizzazione
  • AGENT_RUNTIME_PROJECT_NUMBER: il numero di progetto del progetto che ospita i tuoi agenti

Crea una policy in uscita da agente ad agente

Console

Per definire una policy in uscita da agente ad agente utilizzando la console Cloud de Confiance , segui questi passaggi:

  1. Nella console Cloud de Confiance , vai alla pagina Policy:

    Vai a Policy

  2. Per aggiungere un criterio di accesso uniforme IAM per il traffico in uscita di Agent Gateway, fai clic su Aggiungi policy IAM.
  3. Per selezionare gli agenti di origine, segui questi passaggi:
    1. Per selezionare tutti gli agenti nel registry degli agenti che si trovano nel progetto attualmente selezionato, seleziona Tutti gli agenti.
    2. Per selezionare un agente specifico nel progetto attuale, segui questi passaggi:
      1. Seleziona Agente individuale. Per trovare l'agente, cercalo utilizzando il campo Filtra .
      2. Seleziona l'agente di origine a cui vuoi concedere l'accesso.
      3. Per selezionare l'agente, fai clic su Ok.
  4. In Destinazione di accesso, fai clic su Agente.
  5. In Seleziona agente, seleziona l'agente di destinazione a cui vuoi che acceda l'agente di origine. Per trovare l'agente, cercalo utilizzando il campo filtro Filtra.
  6. Per creare la policy di autorizzazione IAM e associarla all'agente, fai clic su Crea.

gcloud

  1. Crea una policy di autorizzazione IAM in un file in formato JSON.

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPALS"
        ]
      }
    ]
  }
}

    Sostituisci quanto segue:

    • AGENT_PRINCIPALS: un array di entità per le identità degli agenti di origine. Le entità possono essere un array di una o più entità singole (principal://...) o set di entità (principalSet://...), formattati come segue:
      • Identità degli agenti integrate (Agent Runtime, Gemini Enterprise o Cloud Run con identità dell'agente): principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER, ad esempio:
        • Agent Runtime (Reasoning Engine): principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-agent
        • Gemini Enterprise (Discovery Engine): principal://agents.global.org-123456789012.system.id.goog/resources/discoveryengine/projects/9876543210/locations/global/engines/my-engine/assistants/default_assistant/agents/default/core_assistant
        • Cloud Run (identità agente): principal://agents.global.org-123456789012.system.id.goog/resources/run/projects/9876543210/locations/us-central1/services/my-cloud-run-agent
      • Federazione delle identità per i workload (agenti personalizzati o esterni): principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT, ad esempio principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent

  2. Associa la policy IAM a IAP.

    gcloud iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=agent-registry \
    --agent=AGENT_ID \
    --region=REGION

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto del progetto che contiene la risorsa. In alternativa, puoi associare la policy a una cartella o a un'organizzazione specificando rispettivamente i flag --folder o --organization.
    • AGENT_ID: l'ID dell'agente
    • REGION: la regione in cui si trova la risorsa

Terraform

Per concedere l'accesso in uscita a un agente registrato specifico, configura la risorsa google_iap_agent_registry_agent_iam_member:

resource "google_iap_agent_registry_agent_iam_member" "agent_egress" {
project  = "PROJECT_ID"
location = "REGION"
agent_id = "AGENT_ID"
role     = "roles/iap.egressor"
member   = "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER"
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che ospita il registro degli agenti
  • REGION: la località del registry
  • AGENT_ID: l'ID dell'agente registrato di destinazione
  • ORGANIZATION_ID: ID organizzazione
  • AGENT_RUNTIME_PROJECT_NUMBER: il numero di progetto del progetto dell'agente chiamante

Crea una policy in uscita dall'agente al server MCP

Console

Per definire una policy in uscita dall'agente al server MCP utilizzando la console Cloud de Confiance , segui questi passaggi:

  1. Nella console Cloud de Confiance , vai alla pagina Policy:

    Vai a Policy

  2. Per aggiungere un criterio di accesso uniforme IAM per il traffico in uscita di Agent Gateway, fai clic su Aggiungi policy IAM.
  3. Per selezionare gli agenti di origine, segui questi passaggi:
    1. Per selezionare tutti gli agenti nel registry degli agenti che si trovano nel progetto attualmente selezionato, seleziona Tutti gli agenti.
    2. Per selezionare un agente specifico nel progetto attuale, segui questi passaggi:
      1. Seleziona Agente individuale. Per trovare l'agente, cercalo utilizzando il campo Filtra .
      2. Seleziona l'agente di origine a cui vuoi concedere l'accesso.
      3. Per selezionare l'agente, fai clic su Ok.
  4. In Destinazione di accesso, fai clic su Server MCP.
  5. In Seleziona server MCP, seleziona il server MCP di destinazione a cui vuoi che acceda l'agente di origine. Per trovare il server MCP, cercalo utilizzando il campo Filtra.
  6. Per creare la policy di autorizzazione IAM e associarla al server MCP, fai clic su Crea.

  1. Crea una condizione:

    In Condizioni, fai clic su Aggiungi condizione. Nella finestra di dialogo Aggiungi condizione, segui questi passaggi:

    1. In Titolo, inserisci il nome della condizione.
    2. In Descrizione, inserisci la descrizione della condizione.
    3. Per aggiungere una condizione utilizzando il Generatore di condizioni, segui questi passaggi:
      1. In Tipo di condizione, seleziona il tipo di condizione tra i seguenti:
        1. Nome: l'accesso dell'agente è limitato in base al nome della risorsa a cui viene eseguito l'accesso.
        2. ReadOnly: indica se l'accesso dell'agente è limitato alla lettura dei dati, il che impedisce le operazioni di scrittura da parte dell'agente.
        3. Distruttivo: indica se gli agenti possono eseguire azioni considerate dannose o irreversibili, come l'eliminazione di risorse.
        4. Idempotente: indica se l'accesso dell'agente può essere sostituito.
        5. Open world: se l'agente può interagire con un "open world" di entità esterne (ad esempio, uno strumento di ricerca web). Se imposti questa condizione su "false", l'interazione con l'agente viene considerata chiusa.
      2. In Operatore, seleziona l'operatore booleano.
      3. In Valore, seleziona il valore per la condizione.
    4. Per aggiungere un'altra condizione, fai clic su Aggiungi un'altra condizione.
    5. Per salvare la condizione, fai clic su Salva.

gcloud

Per creare una policy in uscita dall'agente al server MCP utilizzando gcloud CLI, segui questi passaggi:

  1. Crea una policy di autorizzazione IAM in un file in formato JSON.

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPALS"
        ],
        "condition": {
          CONDITION
        }

      }
    ]
  }
}

    Sostituisci quanto segue:

    • AGENT_PRINCIPALS: un array di entità per le identità degli agenti di origine. Le entità possono essere un array di una o più entità singole (principal://...) o set di entità (principalSet://...), formattati come segue:
      • Identità degli agenti integrate (Agent Runtime, Gemini Enterprise o Cloud Run con identità dell'agente): principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER, ad esempio:
        • Agent Runtime (Reasoning Engine): principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-agent
        • Gemini Enterprise (Discovery Engine): principal://agents.global.org-123456789012.system.id.goog/resources/discoveryengine/projects/9876543210/locations/global/engines/my-engine/assistants/default_assistant/agents/default/core_assistant
        • Cloud Run (identità agente): principal://agents.global.org-123456789012.system.id.goog/resources/run/projects/9876543210/locations/us-central1/services/my-cloud-run-agent
      • Federazione delle identità per i workload (agenti personalizzati o esterni): principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT, ad esempio principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent
    • CONDITION:

      Il parametro della condizione, formattato come segue:

      "condition": {
  "title": "CONDITION_TITLE",
  "description": "CONDITION_DESCRIPTION",
  "expression": "CEL_EXPRESSION"
}

      Sostituisci quanto segue:

      • CONDITION_TITLE: il titolo della condizione
      • CONDITION_DESCRIPTION: la descrizione della condizione
      • CEL_EXPRESSION: l'espressione condizionale. Questa espressione deve essere un'espressione CEL valida. Per consentire l'accesso, deve essere valutata come true.

  2. Associa la policy IAM a IAP.

    gcloud iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=agent-registry \
    --mcp-server=MCP_SERVER_ID \\
    --region=REGION

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto del progetto che contiene la risorsa. In alternativa, puoi associare la policy a una cartella o a un'organizzazione specificando rispettivamente i flag --folder o --organization.
    • MCP_SERVER_ID: l'ID del server MCP
    • REGION: la regione in cui si trova la risorsa

    L'esempio seguente mostra una policy di autorizzazione IAM che consente a un agente fai da te l'accesso di sola lettura a uno strumento chiamato GitHubTool utilizzando un tipo di autorizzazione MCP.

    {
"policy": {
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-pool.s3ns.svc.id.goog/subject/ns/default/sa/my-ae-agent"
      ],
      "condition": {
        "title": "Allow AE Agent Read-Only Egress to GitHub MCP server",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') == 'GitHubTool' && api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true && api.getAttribute('iap.googleapis.com/request.auth.type', '') == 'MCP'"
      }
    }
  ]
}
}

Terraform

Per concedere l'accesso in uscita condizionale a un server MCP registrato e ai relativi strumenti, configura la risorsa google_iap_agent_registry_mcp_server_iam_member:

resource "google_iap_agent_registry_mcp_server_iam_member" "mcp_egress" {
project       = "PROJECT_ID"
location      = "REGION"
mcp_server_id = "MCP_SERVER_ID"
role          = "roles/iap.egressor"
member        = "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER"

condition {
  title      = "Allow read-only MCP tool access"
  expression = "api.getAttribute('iap.googleapis.com/mcp.toolName', '') == 'TOOL_NAME' && api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true"
}
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che ospita il registro degli agenti
  • REGION: la località del registry (utilizza global per i server MCP remoti gestiti da Google)
  • MCP_SERVER_ID: l'ID del server MCP registrato
  • ORGANIZATION_ID: ID organizzazione
  • AGENT_RUNTIME_PROJECT_NUMBER: il numero di progetto del progetto dell'agente chiamante
  • TOOL_NAME: il nome dello strumento MCP consentito

Crea una policy in uscita da agente a endpoint

Console

Per definire una policy in uscita da agente a endpoint utilizzando la console Cloud de Confiance , segui questi passaggi:

  1. Nella console Cloud de Confiance , vai alla pagina Policy:

    Vai a Policy

  2. Per aggiungere un criterio di accesso uniforme IAM per il traffico in uscita di Agent Gateway, fai clic su Aggiungi policy IAM.
  3. Per selezionare gli agenti di origine, segui questi passaggi:
    1. Per selezionare tutti gli agenti nel registry degli agenti che si trovano nel progetto attualmente selezionato, seleziona Tutti gli agenti.
    2. Per selezionare un agente specifico nel progetto attuale, segui questi passaggi:
      1. Seleziona Agente individuale. Per trovare l'agente, cercalo utilizzando il campo Filtra .
      2. Seleziona l'agente di origine a cui vuoi concedere l'accesso.
      3. Per selezionare l'agente, fai clic su Ok.
  4. In Destinazione di accesso, fai clic su Endpoint.
  5. In Seleziona endpoint, seleziona l'endpoint di destinazione a cui vuoi che acceda l'agente di origine. Per trovare l'endpoint, cercalo utilizzando il campo Filtra.
  6. Per creare la policy di autorizzazione IAM e associarla all'endpoint, fai clic su Crea.

  1. Crea una condizione:

    In Condizioni, fai clic su Aggiungi condizione. Nella finestra di dialogo Aggiungi condizione, segui questi passaggi:

    1. In Titolo, inserisci il nome della condizione.
    2. In Descrizione, inserisci la descrizione della condizione.
    3. Per aggiungere una condizione utilizzando il Generatore di condizioni, segui questi passaggi:
      1. In Tipo di condizione, seleziona il tipo di condizione tra i seguenti:
        1. Nome: l'accesso dell'agente è limitato in base al nome della risorsa a cui viene eseguito l'accesso.
        2. ReadOnly: indica se l'accesso dell'agente è limitato alla lettura dei dati, il che impedisce le operazioni di scrittura da parte dell'agente.
        3. Distruttivo: indica se gli agenti possono eseguire azioni considerate dannose o irreversibili, come l'eliminazione di risorse.
        4. Idempotente: indica se l'accesso dell'agente può essere sostituito.
        5. Open world: se l'agente può interagire con un "open world" di entità esterne (ad esempio, uno strumento di ricerca web). Se imposti questa condizione su "false", l'interazione con l'agente viene considerata chiusa.
      2. In Operatore, seleziona l'operatore booleano.
      3. In Valore, seleziona il valore per la condizione.
    4. Per aggiungere un'altra condizione, fai clic su Aggiungi un'altra condizione.
    5. Per salvare la condizione, fai clic su Salva.

gcloud

  1. Crea una policy di autorizzazione IAM in un file in formato JSON.

    {
  "policy": {
    "bindings": [
      {
        "role": "roles/iap.egressor",
        "members": [
          "AGENT_PRINCIPALS"
        ]
      }
    ]
  }
}

    Sostituisci quanto segue:

    • AGENT_PRINCIPALS: un array di entità per le identità degli agenti di origine. Le entità possono essere un array di una o più entità singole (principal://...) o set di entità (principalSet://...), formattati come segue:
      • Identità degli agenti integrate (Agent Runtime, Gemini Enterprise o Cloud Run con identità dell'agente): principal://TRUST_DOMAIN/AGENT_UNIQUE_IDENTIFIER, ad esempio:
        • Agent Runtime (Reasoning Engine): principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-agent
        • Gemini Enterprise (Discovery Engine): principal://agents.global.org-123456789012.system.id.goog/resources/discoveryengine/projects/9876543210/locations/global/engines/my-engine/assistants/default_assistant/agents/default/core_assistant
        • Cloud Run (identità agente): principal://agents.global.org-123456789012.system.id.goog/resources/run/projects/9876543210/locations/us-central1/services/my-cloud-run-agent
      • Federazione delle identità per i workload (agenti personalizzati o esterni): principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT, ad esempio principal://iam.googleapis.com/projects/1234567890/locations/global/workloadIdentityPools/my-agent-identity/subject/ns/default/sa/my-agent

  2. Associa la policy IAM a IAP.

    gcloud iap web set-iam-policy agents-iap-policy.json \
    --project=PROJECT_ID \
    --resource-type=agent-registry \
    --endpoint=ENDPOINT_ID \
    --region=REGION

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto del progetto che contiene la risorsa. In alternativa, puoi associare la policy a una cartella o a un'organizzazione specificando rispettivamente i flag --folder o --organization.
    • ENDPOINT_ID: l'ID dell'endpoint
    • REGION: la regione in cui si trova la risorsa

Terraform

Per concedere l'accesso in uscita a un endpoint registrato specifico, configura la risorsa google_iap_agent_registry_endpoint_iam_member:

resource "google_iap_agent_registry_endpoint_iam_member" "endpoint_egress" {
project     = "PROJECT_ID"
location    = "REGION"
endpoint_id = "ENDPOINT_ID"
role        = "roles/iap.egressor"
member      = "principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER"
}

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto che ospita il registro degli agenti
  • REGION: la località del registry
  • ENDPOINT_ID: l'ID dell'endpoint registrato
  • ORGANIZATION_ID: ID organizzazione
  • AGENT_RUNTIME_PROJECT_NUMBER: il numero di progetto del progetto dell'agente chiamante

Autentica il tuo server MCP Cloud Run con IAP

Per configurare l'autenticazione basata su IAP per i server MCP di cui esegui il deployment su Cloud Run, segui questi passaggi:

  1. Abilita IAP su Cloud Run.

  2. Concedi il ruolo Invoker all'agente di servizio IAP:

    gcloud run services add-iam-policy-binding SERVICE_NAME \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-iap.s3ns-system.iam.gserviceaccount.com' \
    --role='roles/run.invoker'

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del servizio
    • PROJECT_NUMBER: il numero del progetto

  3. Abilita IAP su un servizio Cloud Run nuovo o esistente.

    Nuovo servizio

    Per eseguire il deployment di un nuovo servizio, esegui questo comando:

    gcloud run deploy SERVICE_NAME \
  --image=CONTAINER_IMAGE \
  --region=REGION \
  --project=PROJECT_ID \
  --allow-unauthenticated \
  --iap \
  --functional-type=mcp-server

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del servizio
    • CONTAINER_IMAGE: la tua immagine container
    • REGION: la regione in cui esegui il deployment del servizio
    • PROJECT_ID: l'ID del progetto in cui è abilitato Cloud Run.

    Servizio esistente

    Per aggiornare un servizio esistente, esegui questo comando:

    gcloud run services update SERVICE_NAME \
  --region=REGION \
  --iap \
  --functional-type=mcp-server

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del servizio.
    • REGION: la regione.

  4. Crea e configura un client OAuth.

    Segui le istruzioni riportate in Condivisione dei client OAuth per l'accesso programmatico per registrare l'ID client universale del tuo client OAuth da utilizzare con IAP.

    Assicurati di registrare i seguenti valori che ottieni quando completi questo passaggio:

    • ID client OAuth
    • Client secret OAuth
    • URI di reindirizzamento

  5. Configura il tuo client come Gemini CLI o il tuo agente per connettere il server MCP di cui hai eseguito il deployment modificando il file settings.json che si trova nella directory home di Gemini (~/.gemini/).

    Di seguito è riportato un modello settings.json:

    {
  "mcpServers": {
    "my_mcp_server": {
      "httpUrl": "https://SERVICE_URL",
      "oauth": {
        "enabled": "true",
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [ "email", "openid" ],
        "redirectUri": "REDIRECT_URI"
      }
    }
  }
}

    Sostituisci quanto segue:

    • SERVICE_URL: l'URL del tuo servizio Cloud Run.
    • OAUTH_CLIENT_ID: l'ID client del passaggio 2.
    • OAUTH_CLIENT_SECRET: il client secret del passaggio 2.
    • REDIRECT_URI: l'URI di reindirizzamento, che deve corrispondere al passaggio 2.

  6. Verifica di riuscire a connetterti al server MCP.

Passaggi successivi

Panoramica

Visualizza una panoramica di Agent Gateway.

Guida

Configura le norme relative ai contenuti e le norme aziendali

Scopri come configurare le norme relative ai contenuti e alle attività.

Guida

Scopri come testare le policy.