Usa un agente de LangChain

Antes de comenzar

En este instructivo, se supone que leíste y seguiste las instrucciones que se indican en los siguientes documentos:

Obtén una instancia de un agente

Para consultar un LangchainAgent, primero debes crear una instancia nueva o obtener una instancia existente.

Para obtener el objeto LangchainAgent correspondiente a un ID de recurso específico, haz lo siguiente:

SDK de Vertex AI para Python

Ejecuta el siguiente 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)

donde

Biblioteca de solicitudes de Python

Ejecuta el siguiente 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 de 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

Cuando se usa el SDK de Vertex AI para Python, el objeto agent corresponde a una clase AgentEngine que contiene lo siguiente:

  • Un agent.api_resource con información sobre el agente implementado. También puedes llamar a agent.operation_schemas() para devolver la lista de operaciones que admite el agente. Consulta Operaciones admitidas para obtener más detalles.
  • un agent.api_client que permite interacciones de servicio síncronas
  • un agent.async_api_client que permite interacciones de servicio asíncronas

En el resto de esta sección, se supone que tienes una instancia de AgentEngine, llamada agent.

Operaciones admitidas

Se admiten las siguientes operaciones:

  • query: Para obtener una respuesta a una búsqueda de forma síncrona
  • stream_query: Para transmitir una respuesta a una búsqueda.

Ambos métodos, query y stream_query, admiten el mismo tipo de argumentos:

  • input: Son los mensajes que se enviarán al agente.
  • config: Es la configuración (si corresponde) para el contexto de la búsqueda.

Consulta al agente

El comando anterior realiza lo siguiente:

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

es equivalente a lo siguiente (en 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?",
        },
    ]
})

Los roles se usan para ayudar al modelo a distinguir entre los diferentes tipos de mensajes cuando responde. Cuando se omite role en la entrada, el valor predeterminado es "user".

Rol Descripción
system Se usa para indicarle al modelo de chat cómo debe comportarse y proporcionar contexto adicional. No es compatible con todos los proveedores de modelos de chat.
user Representa la entrada de un usuario que interactúa con el modelo, por lo general, en forma de texto o de otra entrada interactiva.
assistant Representa una respuesta del modelo, que puede incluir texto o una solicitud para invocar herramientas.
tool Es un mensaje que se usa para pasar los resultados de la invocación de una herramienta al modelo después de que se recuperaron datos o procesamiento externos.

El type del mensaje también determinará cómo se interpreta el resto del mensaje (consulta Cómo controlar contenido multimodal).

Consulta al agente con contenido multimodal

Usaremos el siguiente agente (que reenvía la entrada al modelo y no usa ninguna herramienta) para ilustrar cómo pasar entradas multimodales a un agente:

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

Los mensajes multimodales se representan a través de bloques de contenido que especifican un type y los datos correspondientes. En general, para el contenido multimodal, especificarías que type sea "media", que file_uri apunte a un URI de Cloud Storage y que mime_type interprete el archivo.

Imagen 

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

Video 

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

Audio 

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 obtener la lista de tipos de MIME compatibles con Gemini, consulta la documentación sobre los siguientes temas:

Consulta al agente con una configuración ejecutable

Cuando consultas al agente, también puedes especificar un config para el agente (que sigue el esquema de un RunnableConfig). A continuación, se describen dos situaciones comunes:

  • Parámetros de configuración predeterminados:
    • run_id / run_name: Es el identificador de la ejecución.
    • tags / metadata: Clasificador de la ejecución cuando se realiza el seguimiento con OpenTelemetry.
  • Parámetros de configuración personalizados (a través de configurable):

Observa el siguiente ejemplo:

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)

¿Qué sigue?