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

A Identidade do Agente permite provisionar uma identidade gerenciada para os agentes que você cria e implanta no Agent Runtime na Gemini Enterprise Agent Platform usando a Agents CLI e o Kit de Desenvolvimento de Agente (ADK). O agente implantado pode se autenticar nos serviços doGoogle Cloud e recuperar credenciais do gerenciador de autenticação de Identidade do Agente sem gerenciamento manual de credenciais.

Antes de começar

  1. Ative as APIs Agent Identity, Agent Platform, Agent Registry e App Hub, se ainda não estiverem ativadas.

    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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  2. Verifique se você tem o papel de 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 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: 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 disponíveis apenas na região global

    Para usar um modelo que só está disponível 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-o 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 o agente, faça o seguinte:

    1. Acesse http://localhost:8501. Se preferir, se 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 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 o processo terminar, a CLI vai mostrar uma mensagem de confirmação e um link para o playground do agente no console do Google Cloud .

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

    1. No console do Google Cloud , 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: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

A seguir