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 nos serviços Google Cloud e recuperar credenciais do gerenciador de autenticação de identidade do agente.

Antes de começar

  1. Ative as APIs Identidade do Agente, Agent Platform, Agent Registry e App Hub, se alguma delas ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  2. Verifique se você tem o papel Usuário da Agent Platform (roles/aiplatform.user) no seu 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 o uv e execute a configuração do 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 de aplicativo padrão (app) para corresponder ao nome do agente (AGENT_NAME, por exemplo, maps_agent). Os nomes de 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 dele. Atualize o valor de MODEL em agent.py para corresponder ao modelo escolhido.

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

    Para usar um modelo disponível apenas na região global, modifique agent.py para que seu 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(

      Mude para fazer referência à 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 de diretórios 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 seu agente, faça o seguinte:

    1. Acesse http://localhost:8501. 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 seu agente no Google Cloud:

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

    Substitua:

    • PROJECT_ID: o ID do projeto do Google Cloud .

    • LOCATION: a região com disponibilidade em que você quer implantar o agente (por exemplo, us-west1).

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

  12. Recupere o ID do SPIFFE do seu agente (identidade do agente):

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

      Acessar "Implantações"

    2. Para copiar o ID do SPIFFE do seu 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