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 plataforma de agentes do Gemini Enterprise com a identidade do agente ativada.

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

Antes de começar

  1. Ative a API Agent Identity Connector.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  2. Verifique se você tem o papel de Usuário da Vertex AI (roles/aiplatform.user) no seu projeto.

Criar e implantar o agente

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

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

    pip install google-agents-cli uv
agents-cli setup

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

    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:

    Observação: a árvore a seguir destaca os arquivos de configuração relevantes e pode não representar todos os arquivos no seu diretório.

    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):

    mv app AGENT_NAME

    Em seguida, 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",
)

  4. Ative a identidade do agente criando um arquivo de configuração:

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

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

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

  6. 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

    Verifique seu agente localmente:

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

    Para validar seu agente, faça o seguinte:

    1. Acesse http://localhost:8501.
    2. Na interface de chat, envie um comando de teste para verificar a resposta.

  7. 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 em que você quer implantar o agente (por exemplo, us-west1).

    Quando a implantação for concluída, a CLI vai mostrar uma mensagem de confirmação e um link para o playground do seu agente no console do Google Cloud .

  8. Recupere o ID do SPIFFE do seu agente (identidade do agente) no consoleGoogle Cloud :

    1. No console Google Cloud , acesse a página Agent Platform.
    2. Clique na guia Implantações e selecione o agente implantado.
    3. Copie o valor de Identidade do agente (por exemplo, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

A seguir