Desenvolva e implemente agentes no Vertex AI Agent Engine

Desenvolva e implemente agentes no Vertex AI Agent Engine

Esta página demonstra como criar e implementar um agente no Vertex AI Agent Engine Runtime através das seguintes frameworks de agentes:

• LangGraph

• LangChain

• AG2

• Pipeline de consultas do LlamaIndex (pré-visualização)

Este guia de início rápido explica os seguintes passos:

• Configure o seu projeto Google Cloud .

• Instale o SDK Vertex AI para Python e a framework escolhida.

• Desenvolver um agente de câmbio.

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

• Teste o agente implementado.

Para o guia de início rápido com o Agent Development Kit, consulte o artigo Desenvolva e implemente agentes no Vertex AI Agent Engine com o Agent Development Kit.

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:

   LangGraph

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

   LangChain

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

   AG2

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

   LlamaIndex

   Pré-visualização

   Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

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

2. Autentique-se como utilizador

   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.

   Shell local

   Execute o seguinte comando:

   gcloud auth application-default login

   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:

   1. (Opcional) Antes de testar um agente que desenvolve, tem de importar o Vertex AI Agent Engine e inicializar o SDK da seguinte forma:

      Projeto do Google Cloud

      import vertexai
      
      vertexai.init(
          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
      
      vertexai.init(
          api_key="API_KEY"
      )
      

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

   2. Antes de implementar um agente, tem de importar o Vertex AI Agent Engine e inicializar o SDK da seguinte forma:

      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
      
      client = vertexai.Client(
          api_key="API_KEY"
      )
      

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

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:

   LangGraph

   from vertexai import agent_engines
   
   agent = agent_engines.LanggraphAgent(
       model="gemini-2.0-flash",
       tools=[get_exchange_rate],
       model_kwargs={
           "temperature": 0.28,
           "max_output_tokens": 1000,
           "top_p": 0.95,
       },
   )
   

   LangChain

   from vertexai import agent_engines
   
   agent = agent_engines.LangchainAgent(
       model="gemini-2.0-flash",
       tools=[get_exchange_rate],
       model_kwargs={
           "temperature": 0.28,
           "max_output_tokens": 1000,
           "top_p": 0.95,
       },
   )
   

   AG2

   from vertexai import agent_engines
   
   agent = agent_engines.AG2Agent(
       model="gemini-2.0-flash",
       runnable_name="Get Exchange Rate Agent",
       tools=[get_exchange_rate],
   )
   

   LlamaIndex

   Pré-visualização

   Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

   from vertexai.preview import reasoning_engines
   
   def runnable_with_tools_builder(model, runnable_kwargs=None, **kwargs):
       from llama_index.core.query_pipeline import QueryPipeline
       from llama_index.core.tools import FunctionTool
       from llama_index.core.agent import ReActAgent
   
       llama_index_tools = []
       for tool in runnable_kwargs.get("tools"):
           llama_index_tools.append(FunctionTool.from_defaults(tool))
       agent = ReActAgent.from_tools(llama_index_tools, llm=model, verbose=True)
       return QueryPipeline(modules = {"agent": agent})
   
   agent = reasoning_engines.LlamaIndexQueryPipelineAgent(
       model="gemini-2.0-flash",
       runnable_kwargs={"tools": [get_exchange_rate]},
       runnable_builder=runnable_with_tools_builder,
   )
   

3. Teste o agente localmente:

   LangGraph

   agent.query(input={"messages": [
       ("user", "What is the exchange rate from US dollars to SEK today?"),
   ]})
   

   LangChain

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

   AG2

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

   LlamaIndex

   Pré-visualização

   Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

   agent.query(
       input="What is the exchange rate from US dollars to SEK today?"
   )
   

Implemente um agente

Implemente o agente criando um recurso reasoningEngine no Vertex AI:

LangGraph

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

LangChain

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

AG2

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

LlamaIndex

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

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

Use um agente

Teste o agente implementado enviando uma consulta:

LangGraph

remote_agent.query(input={"messages": [
    ("user", "What is the exchange rate from US dollars to SEK today?"),
]})

LangChain

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

AG2

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

LlamaIndex

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

remote_agent.query(
    input="What is the exchange rate from US dollars to SEK today?"
)

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.