Desenvolva e implemente agentes no Vertex AI Agent Engine com o Agent Development Kit

Desenvolva e implemente agentes no Vertex AI Agent Engine com o Agent Development Kit

Esta página demonstra como criar e implementar um agente no tempo de execução do Vertex AI Agent Engine através do Agent Development Kit (ADK). Este início rápido explica os seguintes passos:

• Configure o seu projeto Google Cloud .

• Instale o SDK Vertex AI para Python e ADK.

• Desenvolver um agente de câmbio.

• Implemente o agente no tempo de execução do Vertex AI Agent Engine.

• Teste o agente implementado.

Também pode usar os seguintes inícios rápidos alternativos para o ADK:

• Início rápido do ADK: O início rápido do ADK é executado inteiramente no seu computador e pressupõe que está a usar um IDE local e acesso ao terminal.

• Agent Starter Pack: uma coleção de modelos de agentes de IA generativa prontos para produção criados para o Vertex AI Agent Engine.

Para o guia de início rápido que usa estruturas suportadas que não o Agent Development Kit, consulte o artigo Desenvolva e implemente agentes no Vertex AI Agent Engine.

Antes de começar

Nota: para ativar APIs, precisa da autorização serviceusage.services.enable. Se não tiver esta autorização, peça ao seu administrador para lhe conceder a função de administrador de utilização de serviços (roles/serviceusage.serviceUsageAdmin).

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 Vertex AI 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 Vertex AI 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 autorizações de que precisa para usar o Vertex AI Agent Engine, peça ao seu administrador para lhe conceder as seguintes funções de IAM no seu projeto:

• Utilizador do Vertex AI (roles/aiplatform.user)
• Administrador de armazenamento (roles/storage.admin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Instale e inicialize o SDK Vertex AI para Python

1. Execute o seguinte comando para instalar o SDK Vertex AI para Python e outros pacotes necessários:

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

2. Autentique-se como utilizador

   Shell local

   Execute o seguinte 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

   Não é necessária nenhuma ação.

   Modo expresso

   Se estiver a usar o Vertex AI no modo expresso, não é necessária nenhuma ação.

3. Execute o seguinte código para importar o Vertex AI Agent Engine e inicializar o SDK:

   Projeto do Google Cloud

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

   Onde:

   • PROJECT_ID é o Google Cloud ID do projeto no qual desenvolve e implementa agentes

   • LOCATION é uma das regiões suportadas.

   Modo expresso

   Se estiver a usar o Vertex AI no modo expresso, execute o seguinte código:

   import vertexai
   from vertexai import agent_engines
   
   vertexai.init(
       key="API_KEY"
   )
   

   onde API_KEY é a chave da API que usa para autenticar o agente.

   Nota: para implementar o agente através do objeto do agente, tem de usar o modo expresso com faturação.

Desenvolva um agente

1. Desenvolva uma ferramenta de câmbio para o 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:

   Nota: o teste de um agente 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)
   

   onde USER_ID é um ID definido pelo utilizador com um limite de 128 carateres.

Implemente um agente

Implemente o agente criando um recurso reasoningEngine no Vertex AI:

Nota: a implementação de um agente ADK no Vertex AI Agent Engine gera automaticamente um recurso de sessão gerido. Pode eliminar o recurso de sessão gerida juntamente com o agente na secção Limpeza.

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

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

Use um agente

Teste o agente implementado 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 incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta página, siga estes passos.

remote_agent.delete(force=True)

O que se segue?

• Explore os blocos de notas.
• Configure o ambiente.
• Desenvolva um agente.
• Implemente um agente.
• Use um agente.
• Faça a gestão de um agente.
• Receba apoio técnico.