Usar un agente de LangChain

Antes de empezar

En este tutorial se da por hecho que has leído y seguido las instrucciones de los siguientes artículos:

Obtener una instancia de un agente

Para consultar un LangchainAgent, primero debes crear una instancia o obtener una instancia que ya tengas.

Para obtener el LangchainAgent correspondiente a un ID de recurso específico, sigue estos pasos:

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 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 que se devuelva la lista de operaciones que admite el agente. Consulta Operaciones admitidas para obtener más información.
  • 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 presupone que tienes una instancia de AgentEngine llamada agent.

Operaciones admitidas

Se admiten las siguientes operaciones:

  • query: para obtener una respuesta a una consulta de forma síncrona.
  • stream_query: para transmitir una respuesta a una consulta.

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

  • input: los mensajes que se enviarán al agente.
  • config: la configuración (si procede) del contexto de la consulta.

Consultar el agente

El comando:

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

es equivalente a lo siguiente (en formato completo):

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 al responder. Si se omite role en la entrada, el valor predeterminado es "user".

Rol Descripción
system Se usa para indicar al modelo de chat cómo debe comportarse y proporcionar contexto adicional. No todos los proveedores de modelos de chat admiten esta función.
user Representa la entrada de un usuario que interactúa con el modelo, normalmente en forma de texto u otra entrada interactiva.
assistant Representa una respuesta del modelo, que puede incluir texto o una solicitud para invocar herramientas.
tool Mensaje que se usa para devolver los resultados de una invocación de herramienta al modelo después de que se hayan obtenido datos o se haya realizado un procesamiento externos.

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

Consultar al agente con contenido multimodal

Usaremos el siguiente agente (que reenvía la entrada al modelo y no usa ninguna herramienta) para mostrar cómo enviar 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 mediante bloques de contenido que especifican un type y los datos correspondientes. En general, para el contenido multimodal, se debe especificar 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"},
]})

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

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 ver la lista de tipos MIME admitidos por Gemini, consulta la documentación sobre:

Consultar el 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). Estos son dos casos habituales:

  • Parámetros de configuración predeterminados:
    • run_id / run_name: identificador de la ejecución.
    • tags / metadata: clasificador de la ejecución cuando se rastrea con OpenTelemetry.
  • Parámetros de configuración personalizados (mediante configurable):

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

Siguientes pasos