Use um agente LangChain

Antes de começar

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

Obtenha uma instância de um agente

Para consultar um LangchainAgent, primeiro tem de criar uma nova instância ou obter uma instância existente.

Para obter o LangchainAgent correspondente a um ID do recurso específico:

SDK Vertex AI para Python

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)

onde

Biblioteca de pedidos 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

Quando usa o SDK Vertex AI para Python, o objeto agent corresponde a uma classe AgentEngine que contém o seguinte:

  • Um agent.api_resource com informações sobre o agente implementado. Também pode chamar agent.operation_schemas() para devolver a lista de operações que o agente suporta. Consulte o artigo Operações suportadas para ver detalhes.
  • Um agent.api_client que permite interações de serviço síncronas
  • Um agent.async_api_client que permite interações de serviço assíncronas

O resto desta secção pressupõe que tem uma instância do AgentEngine, denominada agent.

Operações compatíveis

As seguintes operações são suportadas:

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

Os métodos query e stream_query suportam o mesmo tipo de argumentos:

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

Consultar o agente

O comando:

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?",
        },
    ]
})

As funções são usadas para ajudar o modelo a distinguir entre diferentes tipos de mensagens ao responder. Quando o role é omitido na entrada, a predefinição é "user".

Função Descrição
system Usado para indicar ao modelo de chat como se comportar e fornecer contexto adicional. Não é suportado por todos os fornecedores de modelos de chat.
user Representa a entrada de um utilizador que interage com o modelo, normalmente sob a forma de texto ou outra entrada interativa.
assistant Representa uma resposta do modelo, que pode incluir texto ou um pedido para invocar ferramentas.
tool Uma mensagem usada para transmitir os resultados de uma invocação de ferramenta de volta ao modelo após a obtenção de dados ou processamento externos.

O type da mensagem também determina como o resto da mensagem é interpretado (consulte a secção Processar conteúdo multimodal).

Consultar o agente com conteúdo multimodal

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

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

As mensagens multimodais são representadas através de blocos de conteúdo que especificam um type e os dados correspondentes. Em geral, para conteúdo multimodal, especifica que o type é "media", o file_uri aponta para um URI do Cloud Storage e o mime_type para interpretar o ficheiro.

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 ver a lista de tipos MIME suportados pelo Gemini, consulte a documentação em:

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

Quando consulta o agente, também pode especificar um config para o agente (que segue o esquema de um RunnableConfig). Dois cenários comuns são:

Por 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)

O que se segue?