Criar e implantar um agente com a CLI do agente e a identidade do agente

Este guia mostra como criar e implantar um agente no Agent Runtime na Gemini Enterprise Agent Platform com a Identidade do agente ativada.

A Identidade do agente atribui uma identidade SPIFFE segura ao agente implantado. O agente usa essa identidade para autenticar serviços Google Cloud e recuperar credenciais do gerenciador de autenticação da Identidade do agente.

Antes de começar

  1. Ative as APIs Agent Identity, Agent Platform, Agent Registry e App Hub.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pela função Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pela função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

    Ativar as APIs

  2. Verifique se você tem a função Usuário da Agent Platform (roles/aiplatform.user) no projeto.

Criar e implantar o agente

Crie um agente de amostra usando google-agents-cli e implante-o com a Identidade do agente:

  1. Instale uv e execute a configuração google-agents-cli:

    pip install uv
uvx google-agents-cli setup

  2. Crie um projeto de agente usando o modelo de protótipo:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Substitua AGENT_PROJECT pelo nome do novo diretório do projeto do agente (por exemplo, maps-agent).

    Esse comando gera a seguinte estrutura de diretório do projeto:

    AGENT_PROJECT/
├── app/                       # Core agent code
│   ├── agent.py               # Main agent logic
│   ├── fast_api_app.py        # Client application logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit and integration tests
├── GEMINI.md                  # Development guide
└── pyproject.toml             # Project dependencies

  3. Renomeie a pasta do aplicativo padrão (app) para corresponder ao nome do agente (AGENT_NAME, por exemplo, maps_agent). Os nomes dos agentes precisam ser um identificador Python válido: eles precisam começar com uma letra e conter apenas letras, números e sublinhados.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Atualize o arquivo de configuração agent.py para refletir o novo nome:

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  5. Escolha um modelo para usar com base na disponibilidade regional. Atualize o valor de MODEL em agent.py para corresponder ao modelo escolhido.

    Solução alternativa para modelos que estão disponíveis apenas na global região

    Para usar um modelo que está disponível apenas na região global, modifique agent.py para que o agente possa acessá-lo.

    1. Adicione as seguintes importações:

      from functools import cached_property
from google.genai import Client

    2. Adicione a seguinte subclasse após as importações:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Encontre o seguinte código:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Altere-o para referenciar a nova subclasse:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Ative a Identidade do agente criando um arquivo de configuração:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  7. Crie um arquivo requirements.txt para as dependências de implantação:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Verifique a estrutura do diretório do projeto:

    AGENT_PROJECT/
├── AGENT_NAME/                 # Agent application folder
│   ├── .agent_engine_config.json # Agent Identity configuration
│   ├── agent.py                  # Main agent logic
│   ├── fast_api_app.py           # Client application logic
│   ├── requirements.txt          # Deployment dependencies
│   └── app_utils/                # App helpers
├── tests/                        # Tests
├── GEMINI.md                     # Development guide
└── pyproject.toml                # Project dependencies

  9. Teste o agente localmente:

    uv run adk web . --port 8501 --reload_agents

    Para validar o agente, faça o seguinte:

    1. Acesse http://localhost:8501. Como alternativa, se você estiver usando o Cloud Shell, clique no link fornecido pela saída do servidor da Web.

    2. Na interface de chat, envie um comando de teste para verificar a resposta.

  10. Encerre o servidor com CTRL+C.

  11. Implante o agente em Google Cloud:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Substitua:

    • PROJECT_ID: seu Google Cloud projeto ID.

    • LOCATION: A região compatível em que você quer implantar o agente (por exemplo, us-west1).

    A implantação pode levar alguns minutos para ser concluída. Depois que terminar, a CLI vai gerar uma mensagem de confirmação e um link para o playground do agente no console do Google Cloud .

  12. Recupere o ID SPIFFE do agente (Identidade do agente):

    1. No Google Cloud console do, acesse a página Implantações.

      Acessar "Implantações"

    2. Para copiar o ID SPIFFE do agente para a área de transferência, encontre a linha em que o agente implantado está e, na coluna Identidade dessa linha, clique em Copiar para a área de transferência. A identidade é semelhante a esta: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

A seguir