Desenvolver e implantar agentes no Agent Runtime com o Kit de Desenvolvimento de Agente

Desenvolver e implantar agentes no Agent Runtime com o Kit de Desenvolvimento de Agente

O Agent Runtime permite hospedar agentes desenvolvidos com o Kit de Desenvolvimento de Agente (ADK). Este documento explica como criar, implantar e testar um agente usando o ADK.

Este guia de início rápido orienta você nas seguintes etapas:

• Crie o Google Cloud projeto.
• Instale o SDK da plataforma de agentes para Python e o ADK.
• Desenvolva um agente de câmbio.
• Implante o agente no Agent Runtime.
• Teste o agente implantado.

Você também pode usar os seguintes guias de início rápido alternativos para o ADK:

• Guia de início rápido do ADK: o guia de início rápido do ADK é executado totalmente na sua máquina e pressupõe que você esteja usando um ambiente de desenvolvimento integrado local e acesso ao terminal.
• Pacote inicial do agente: uma coleção de modelos de agentes de IA generativa prontos para produção criados para a plataforma de agentes.

Para o guia de início rápido usando frameworks com suporte diferentes do Kit de Desenvolvimento de Agente, consulte Desenvolver e implantar agentes no Agent Runtime.

Antes de começar

Observação: para ativar as APIs, você precisa da permissão serviceusage.services.enable. Se você não tiver essa permissão, peça ao administrador para conceder a você o papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin).

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Para receber as permissões necessárias a fim de usar o Agent Runtime, peça que o administrador conceda a você os seguintes papéis do IAM no projeto:

• Usuário da plataforma de agentes (roles/aiplatform.user)
• Administrador de armazenamento (roles/storage.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Instalar e inicializar o SDK da plataforma de agentes para Python

1. Execute o seguinte comando para instalar o SDK da plataforma de agentes para Python e outros pacotes necessários:

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,adk]>=1.112

2. Autenticar como um usuário

   Shell local

   Execute este comando:

   gcloud auth application-default login

   Colab

   Execute o seguinte código:

   from google.colab import auth
   
   auth.authenticate_user(project_id="PROJECT_ID")
   

   Cloud Shell

   Nenhuma ação é necessária.

3. Execute o seguinte código para importar a Plataforma de Agentes e inicializar o SDK:

   Projeto do Google Cloud

   import vertexai
   
   client = vertexai.Client(
       project="PROJECT_ID",               # Your project ID.
       location="LOCATION",                # Your cloud region.
   )
   

   Em que:

   • PROJECT_ID é o Google Cloud ID do projeto em que você desenvolve e implanta agentes

   • LOCATION é uma das regiões com suporte.

Desenvolver um agente

1. Desenvolva uma ferramenta de câmbio para seu agente:

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. Instancie um agente:

   from google.adk.agents import Agent
   from vertexai import agent_engines
   
   agent = Agent(
       model="gemini-2.0-flash",
       name='currency_exchange_agent',
       tools=[get_exchange_rate],
   )
   
   app = agent_engines.AdkApp(agent=agent)
   

3. Teste o agente localmente:

   **Observação**: o teste de um agente do ADK localmente usa sessões na memória.

   async for event in app.async_stream_query(
       user_id="USER_ID",
       message="What is the exchange rate from US dollars to SEK today?",
   ):
       print(event)
   

   em que USER_ID é um ID definido pelo usuário com um limite de 128 caracteres.

Implantar um agente

Implante o agente criando um reasoningEngine recurso na plataforma de agentes:

Observação: a implantação de um agente do ADK na plataforma de agentes gera automaticamente um recurso de sessão gerenciada. É possível excluir o recurso de sessão gerenciada junto com o agente na seção "Limpeza".

remote_agent = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "STAGING_BUCKET",
        "identity_type": types.IdentityType.AGENT_IDENTITY,
    }
)

em que STAGING_BUCKET é um bucket do Cloud Storage com o prefixo gs://.

Usar um agente

Teste o agente implantado enviando uma consulta:

async for event in remote_agent.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

Limpar

Para evitar cobranças na conta do Google Cloud pelos recursos usados nesta página, siga as etapas abaixo.

remote_agent.delete(force=True)

A seguir

Guia

Configuração do ambiente de execução da plataforma de agentes

Configure seu ambiente para usar o ambiente de execução da plataforma de agentes.

Guia

Implantar agentes

Conheça as cinco maneiras de implantar um agente no ambiente de execução da plataforma de agentes com base nas suas necessidades de desenvolvimento.

Guia

Gerenciar agentes implantados

Saiba como gerenciar agentes que foram implantados no ambiente de execução gerenciado da plataforma de agentes.

Guia

Usar um agente

Use um agente com o ambiente de execução da plataforma de agentes.

Recurso

Receber suporte

Encontre recursos e suporte para a plataforma de agentes do Google.