Desenvolver e implantar agentes no Vertex AI Agent Engine

Esta página demonstra como criar e implantar um agente no ambiente de execução do Vertex AI Agent Engine usando as seguintes estruturas de agente:

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

  • Crie o projeto Google Cloud .

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

  • Desenvolva um agente de câmbio.

  • Implante o agente no ambiente de execução do Vertex AI Agent Engine.

  • Teste o agente implantado.

Para o guia de início rápido usando o Kit de Desenvolvimento de Agente, consulte Desenvolver e implantar agentes no Vertex AI Agent Engine com o Kit de Desenvolvimento de Agente.

Antes de começar

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

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

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

    8.

    Para receber as permissões necessárias para usar o mecanismo de agente da Vertex AI, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    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 papéis personalizados ou outros papéis predefinidos.

    Instalar e inicializar o SDK do Vertex AI para Python

    1. Execute o seguinte comando para instalar o SDK da 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 

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

    2. Autenticar como usuário

      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.

      Shell local

      Execute este comando:

      gcloud auth application-default login

      Modo expresso

      Se você estiver usando a Vertex AI no modo expresso, nenhuma ação será necessária.

    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 você desenvolve, importe o Vertex AI Agent Engine e inicialize o SDK da seguinte maneira:

        Projeto do Google Cloud

        import vertexai

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

        Em que:

        Modo expresso

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

        import vertexai

vertexai.init(
    api_key="API_KEY"
)

        em que API_KEY é a chave de API usada para autenticar o agente.

      2. Antes de implantar um agente, importe o Vertex AI Agent Engine e inicialize o SDK da seguinte maneira:

        Projeto do Google Cloud

        import vertexai

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

        Em que:

        Modo expresso

        Se você estiver usando a Vertex AI no modo rápido, execute o seguinte código:

        import vertexai

client = vertexai.Client(
    api_key="API_KEY"
)

        em que API_KEY é a chave de API usada para autenticar o agente.

    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:

      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 

      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 

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

    Implantar um agente

    Implante o agente criando um recurso reasoningEngine na 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 

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

    Usar um agente

    Teste o agente implantado 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 

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

    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