Usar um agente do LangChain

Antes de começar

Este tutorial pressupõe que você leu e seguiu as instruções em:

Receber uma instância de um agente

Para consultar um LangchainAgent, primeiro crie uma nova instância ou receba uma instância atual.

Para receber o LangchainAgent que corresponde a um ID de recurso específico:

SDK da Agent Platform

Execute o seguinte código:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

agent = client.agent_engines.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(agent)

em que

Biblioteca de solicitações do Python

Execute o seguinte código:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

API REST 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Ao usar o SDK do Agent Platform, o objeto agent corresponde a uma AgentEngine classe que contém o seguinte:

O restante desta seção pressupõe que você tenha uma instância AgentEngine, nomeada como agent.

Operações com suporte

As seguintes operações são compatíveis:

  • query: para receber uma resposta a uma consulta de forma síncrona.
  • stream_query: para transmitir uma resposta a uma consulta.

Os métodos query e stream_query oferecem suporte ao mesmo tipo de argumentos:

  • input: as mensagens a serem enviadas ao agente.
  • config: a configuração (se aplicável) para o contexto da consulta.

Consultar o agente

Para consultar o agente com uma entrada, use o LangchainAgent.query método:

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

é equivalente ao seguinte (na forma completa):

agent.query(input={
    "input": [ # The input is represented as a list of messages (each message as a dict)
        {
            # The role (e.g. "system", "user", "assistant", "tool")
            "role": "user",
            # The type (e.g. "text", "tool_use", "image_url", "media")
            "type": "text",
            # The rest of the message (this varies based on the type)
            "text": "What is the exchange rate from US dollars to Swedish currency?",
        },
    ]
})

Os papéis são usados para ajudar o modelo a distinguir entre diferentes tipos de mensagens ao responder. Quando o role é omitido na entrada, o padrão é "user".

Papel Descrição
system Usado para informar ao modelo de chat como se comportar e fornecer contexto adicional. Não é compatível com todos os provedores de modelos de chat.
user Representa a entrada de um usuário que interage com o modelo, geralmente na forma de texto ou outra entrada interativa.
assistant Representa uma resposta do modelo, que pode incluir texto ou uma solicitação para invocar ferramentas.
tool Uma mensagem usada para transmitir os resultados de uma invocação de ferramenta de volta ao modelo depois que dados ou processamento externos forem recuperados.

O type da mensagem também determina como o restante da mensagem é interpretado (consulte Processar conteúdo multimodal).

Consultar o agente com conteúdo multimodal

Vamos usar o agente a seguir (que encaminha a entrada para o modelo e não usa nenhuma ferramenta) para ilustrar como transmitir entradas multimodais para um agente:

agent = agent_engines.LangchainAgent(
    model="gemini-2.0-flash",
    runnable_builder=lambda model, **kwargs: model,
)

As mensagens multimodais são representadas por blocos de conteúdo que especificam um type e os dados correspondentes. Em geral, para conteúdo multimodal, especifique o type como "media", o file_uri para apontar para um URI do Cloud Storage, e o mime_type para interpretar o arquivo.

Imagem 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "image/jpeg", "file_uri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg"},
]})

Vídeo 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "video/mp4", "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"},
]})

Áudio 

agent.query(input={"input": [
    {"type": "text", "text": "Describe the attached media in 5 words!"},
    {"type": "media", "mime_type": "audio/mp3", "file_uri": "gs://cloud-samples-data/generative-ai/audio/pixel.mp3"},
]})

Para conferir a lista de tipos MIME com suporte do Gemini, acesse a documentação sobre:

Consultar o agente com uma configuração executável

Ao consultar o agente, também é possível especificar um config para o agente (que segue o esquema de um RunnableConfig). Dois cenários comuns são:

Como exemplo:

import uuid

run_id = uuid.uuid4()  # Generate an ID for tracking the run later.

response = agent.query(
    input="What is the exchange rate from US dollars to Swedish currency?",
    config={  # Specify the RunnableConfig here.
        "run_id": run_id                               # Optional.
        "tags": ["config-tag"],                        # Optional.
        "metadata": {"config-key": "config-value"},    # Optional.
        "configurable": {"session_id": "SESSION_ID"}   # Optional.
    },
)

print(response)

A seguir