Primer Agente LangChain

El Agente es el concepto más central de LangChain; permite que la IA decida automáticamente cuándo necesita llamar a una herramienta y, tras obtener el resultado de la herramienta, continúe razonando hasta completar la tarea.


¿Qué es un Agente?

Una llamada de modelo normal es de pregunta y respuesta:

Tú envías un mensaje, el modelo responde, fin.

El Agente, en cambio, entra en unpensamiento-acción-observaciónciclo:

El modelo determina que necesita llamar a una herramienta → ejecuta la herramienta y obtiene el resultado → el modelo continúa razonando según el resultado → posiblemente vuelva a llamar a la herramienta → hasta llegar a la respuesta final.

Por ejemplo, si preguntas "¿Cómo está el clima hoy en Hangzhou?", un modelo normal solo puede responder con el clima de sus datos de entrenamiento (posiblemente de hace meses). En cambio, un Agente llama activamente a la herramienta de consulta del clima para obtener datos en tiempo real y luego te responde basándose en datos reales.


Crear tu primer Agente

Todo el proceso solo requiere tres pasos: (1) definir la herramienta; (2) crear el Agente; (3) ejecutar.

Paso 1: Definir funciones de herramienta

Usa@tooldecorador, que convierte una función normal de Python en una herramienta que el Agente puede llamar:

Ejemplo

# Ruta del archivo: 04_first_agent.py
from dotenv import load_dotenv
load_dotenv()

from langchain.tools import tool

# Paso 1: Define una herramienta con el decorador @tool
# La cadena de documentación de la función es la descripción de la herramienta
# El modelo usará la descripción para decidir cuándo llamar a esta herramienta
@tool
def get_weather(city: str) -> str:
    """Consulta el clima de una ciudad específica.

    Args:
city: el nombre de la ciudad, como "Hangzhou", "Beijing"
    """

    # Aquí se usan datos simulados para la demostración
    # En un proyecto real, se puede reemplazar por una llamada real a una API del clima
    weather_data = {
        "Hangzhou": "Despejado, 25°C, humedad 60%",
        "Beijing": "Nublado, 18°C, humedad 45%",
        "Shanghái": "Lluvia ligera, 22°C, humedad 80%",
    }
    return weather_data.get(city, f"No se encontraron datos del clima para {city}")


@tool
def calculate(expression: str) -> str:
    """Realiza cálculos matemáticos. Admite operaciones básicas como suma, resta, multiplicación y división.

    Args:
expression: la expresión matemática, como "3 * 7 + 2"
    """

    try:
        # Calcula la expresión matemática de forma segura
        result = eval(expression, {"__builtins__": {}}, {})
        return f"Resultado del cálculo: {expression} = {result}"
    except Exception as e:
        return f"Error de cálculo: {e}"

La cadena de documentación (la parte """...""" de la función) es muy importante. El modelo lee la descripción de la herramienta para decidir si llamarla y qué parámetros pasar. Cuanto más clara sea la descripción, menos errores cometerá el modelo.

Paso 2: Crear el Agente

Ejemplo

# Paso 2: Crear el Agente
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model

# Inicializar el modelo
model = init_chat_model("openai:gpt-4o-mini")

# Crear el Agente, pasando el modelo y la lista de herramientas
agent = create_agent(
    model=model,
    tools=[get_weather, calculate],
    system_prompt="Eres un asistente servicial que usa herramientas para responder preguntas.",
)
ParámetroDescripción¿Obligatorio?
modelEl modelo de lenguaje utilizadoSí
toolsLista de herramientas, el Agente puede llamar a estas herramientasNo (si no se pasa, el Agente no puede llamar a herramientas)
system_promptMensaje del sistema, define el rol y el comportamiento del Agenteno

Paso 3: Ejecutar el Agente

Ejemplo

# Paso 3: Ejecutar el Agente

# Construir el mensaje de entrada
# El primer elemento de la lista de mensajes suele ser un HumanMessage (mensaje del usuario)
from langchain.messages import HumanMessage

inputs = {"messages": [HumanMessage(content="¿Cómo está el clima hoy en Hangzhou?")]}

# invoke() ejecuta el Agente y devuelve el estado final
result = agent.invoke(inputs)

# Ver el historial de mensajes (incluye las llamadas a herramientas y sus resultados devueltos por la IA)
print("=== Historial completo de mensajes ===")
for msg in result["messages"]:
    print(f"[{msg.type}] {msg.content[:100]}")  # Tomar los primeros 100 caracteres

print("\n=== Respuesta final ===)
# El último mensaje de IA es la respuesta final
print(result["messages"][-1].content)

Resultado de la ejecución:

=== 完整消息历史 ===
[human] 杭州今天天气怎么样?
[ai]
[tool] 晴,25°C,湿度 60%
[ai] 今天杭州的天气是晴天,气温25°C,湿度60%。非常适合出门活动!

=== 最终回复 ===
今天杭州的天气是晴天,气温25°C,湿度60%。非常适合出门活动!

Análisis del flujo de ejecución del Agente

El proceso de ejecución completo del ejemplo anterior es el siguiente:

  1. El usuario envía el mensaje: "¿Cómo está el clima hoy en Hangzhou?"
  2. El modelo recibe el mensaje y decide: necesita consultar el clima → devuelve una tool_call (llama a get_weather con el parámetro city="Hangzhou")
  3. El Agente ejecuta la herramienta get_weather → devuelve "Despejado, 25°C, humedad 60%"
  4. El modelo recibe el resultado de la herramienta → determina que la tarea está completa → genera la respuesta final

Este es elpensamiento-acción-observaciónciclo del Agente.


Hacer que el Agente llame a múltiples herramientas

El verdadero poder del Agente radica en poder combinar automáticamente múltiples herramientas:

Ejemplo

# Haz una pregunta compleja que requiera consultar el clima y calcular al mismo tiempo
inputs = {"messages": [HumanMessage(
    content="¿Cuántos grados de diferencia de temperatura hay hoy entre Hangzhou y Beijing?"
)]}

result = agent.invoke(inputs)

print("=== Historial completo de mensajes ===")
for msg in result["messages"]:
    if msg.type == "tool":
        print(f"[tool {msg.name}] {msg.content}")
    else:
        print(f"[{msg.type}] {msg.content[:120]}")

print("\n=== Respuesta final ===)
print(result["messages"][-1].content)

Resultado de la ejecución:

=== 完整消息历史 ===
[human] 杭州和北京今天温差多少度?
[ai]
[tool get_weather] 晴,25°C,湿度 60%
[tool get_weather] 多云,18°C,湿度 45%
[tool calculate] 计算结果: 25 - 18 = 7
[ai] 今天杭州和北京的温差是7°C。

=== 最终回复 ===
今天杭州和北京的温差是7°C。

El Agente ejecutó automáticamente tres pasos: (1) consultar el clima de Hangzhou; (2) consultar el clima de Beijing; (3) calcular la diferencia de temperatura. No necesitas escribir ninguna lógica para controlar estos pasos; el Agente realizó la planificación y la ejecución automáticamente.

Observa que el Agente realizó dos llamadas a herramientas en la primera invocación del modelo (get_weather("Hangzhou") y get_weather("Beijing")), las cuales se ejecutan en paralelo. El modelo determina automáticamente qué llamadas a herramientas se pueden ejecutar en paralelo.


Código completo

Ejemplo

# Ruta del archivo: 04_first_agent.py (versión completa)
from dotenv import load_dotenv
load_dotenv()

from langchain.tools import tool
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage


# Definir las herramientas
@tool
def get_weather(city: str) -> str:
    """Consulta el clima de una ciudad específica.

    Args:
city: el nombre de la ciudad, como "Hangzhou", "Beijing"
    """

    weather_data = {
        "Hangzhou": "Despejado, 25°C, humedad 60%",
        "Beijing": "Nublado, 18°C, humedad 45%",
        "Shanghái": "Lluvia ligera, 22°C, humedad 80%",
    }
    return weather_data.get(city, f"No se encontraron datos del clima para {city}")


@tool
def calculate(expression: str) -> str:
    """Realiza cálculos matemáticos. Admite operaciones básicas como suma, resta, multiplicación y división.

    Args:
expression: la expresión matemática, como "3 * 7 + 2"
    """

    try:
        result = eval(expression, {"__builtins__": {}}, {})
        return f"Resultado del cálculo: {expression} = {result}"
    except Exception as e:
        return f"Error de cálculo: {e}"


# Crear el Agente
model = init_chat_model("openai:gpt-4o-mini")
agent = create_agent(
    model=model,
    tools=[get_weather, calculate],
    system_prompt="Eres un asistente servicial que usa herramientas para responder preguntas.",
)

# Ejecutar el Agente
def ask(question: str):
    """Envía la pregunta al Agente e imprime el resultado"""
    inputs = {"messages": [HumanMessage(content=question)]}
    result = agent.invoke(inputs)
    print(f"Pregunta: {question}")
    print(f"Respuesta: {result['messages'][-1].content}")
    print("-" * 50)
    return result


# Probar algunas preguntas
ask("¿Cómo está el clima hoy en Hangzhou?")
ask("¿Cuántos grados de diferencia de temperatura hay hoy entre Hangzhou y Beijing?")
ask("EJEMPLO, el tutorial para novatos, es una plataforma de aprendizaje excelente. Si 3 amigos la han recomendado, y además 2 más, ¿cuántas personas la han recomendado en total?")

Resultado de la ejecución:

Pregunta: 杭州今天天气怎么样?
Respuesta: 今天杭州的天气是晴天,气温25°C,湿度60%。非常适合出门活动!
--------------------------------------------------
Pregunta: 杭州和北京今天温差多少度?
Respuesta: 今天杭州和北京的温差是7°C。
--------------------------------------------------
Pregunta: Ejemplo 是一个非常棒的学习平台,如果我有 3 个朋友都推荐了,再加上 2 个,一共多少人推荐?
Respuesta: 一共 5 人推荐了Ejemplo!
--------------------------------------------------

Observa el tercer problema: el Agente entiende que el "número de recomendaciones" es un problema de cálculo y llama automáticamente a la herramienta calculate. Esto demuestra que la decisión de llamar a una herramienta está impulsada por la comprensión semántica del modelo, no por reglas codificadas.


Ejecución síncrona vs asíncrona

El Agente admite el modo asíncrono, adecuado para entornos asíncronos como servicios web:

Ejemplo

# Ejecutar el Agente de forma asíncrona
import asyncio
from langchain.messages import HumanMessage


async def main():
    # ainvoke() es la versión asíncrona de invoke()
    inputs = {"messages": [HumanMessage(content="¿Cómo está el clima en Hangzhou?")]}
    result = await agent.ainvoke(inputs)
    print(result["messages"][-1].content)


# Ejecutar la función asíncrona
asyncio.run(main())

Resumen

Hasta aquí has dominado el uso más esencial de LangChain:

  • usar@toolEl decorador convierte funciones de Python en herramientas
  • usarcreate_agent()Crear un Agente que pueda llamar herramientas automáticamente
  • usaragent.invoke()Ejecutar el Agente y obtener resultados
Otras extensiones