Documentación de IA agéntica de LangChain: Herramientas y modo JSON
La mayoría de la documentación de IA agéntica de LangChain asume una clase de modelo propia del proveedor, pero cualquier endpoint compatible con OpenAI funciona con ChatOpenAI una vez que estableces una URL base. Esta guía conecta LangChain a esta API y construye un agente con llamadas a funciones paso a paso.
Actualizado
Puntos clave
- Usa ChatOpenAI con base_url configurado a esta API y modelo configurado a
uncensored. - Las llamadas a funciones y el modo JSON son compatibles, por lo que bind_tools y response_format funcionan según lo documentado.
- Limita los bucles de agente, valida los argumentos de las herramientas y mantén max_concurrency en 8 o menos con una clave completa.
- El streaming sobre SSE devuelve el uso de tokens al final, lo que te ayuda a rastrear el costo de cada ejecución de agente.

Lo que necesitas antes de comenzar
Si estás leyendo documentación de IA agéntica de LangChain y te preguntas qué cambia cuando el modelo no es del proveedor de los ejemplos, la respuesta es muy poco. Un agente en LangChain es un bucle: el modelo lee la conversación, decide si llamar a una herramienta, tu código ejecuta la herramienta y el resultado vuelve al modelo hasta que produce una respuesta final. El endpoint del modelo solo tiene que soportar completiones de chat con llamadas a funciones, y esta API lo hace.
Necesitas tres cosas: una clave de API de la página de claves, Python 3.10 o superior, y los paquetes de abajo. La base URL es https://api.unlimitedaiapi.com/v1 y el ID del modelo es uncensored. Es un modelo de pesos abiertos ejecutado por un proveedor independiente, así que no hay lista de modelos para elegir; GET /v1/models lo devuelve para el descubrimiento del cliente.
pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"Paso 1: conectar ChatOpenAI al endpoint
La clase ChatOpenAI de LangChain acepta una base_url personalizada. Todo lo demás permanece igual, incluidas las variantes invoke, stream, batch y async.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0.2,
)
print(llm.invoke("Reply with one short sentence.").content)
Si esto imprime una oración, la autenticación, el enrutamiento y el nombre del modelo son correctos. La autenticación es el encabezado estándar Authorization: Bearer, que la clase añade por ti. Un error común es omitir /v1 en la base URL, lo que suele hacer que la primera llamada falle.
Paso 2: definir herramientas y vincularlas
Las herramientas son funciones de Python simples con un docstring. El docstring y las anotaciones de tipo se convierten en el esquema que ve el modelo, así que escríbelos como si explicaras la función a un nuevo colega.
import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])
ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)
La lista impresa contiene una llamada con el nombre get_order_status y argumentos como {"order_id": "A100"}. Bajo el capó, LangChain envía tu función como una entrada en la matriz tools de la petición de chat completions, y la API admite tools, tool_choice y tool_calls en streaming. Para forzar una llamada a herramienta, pasa tool_choice a bind_tools.
Por qué la temperatura es baja
Los agentes encadenan varias llamadas al modelo, por lo que un argumento mal formado puede desviar una ejecución. Una temperatura de 0 a 0,2 hace que la selección de herramientas sea más repetible. Auméntala solo para el paso de respuesta final si quieres prosa más variada.
Paso 3: ejecutar el bucle del agente
Escribir el bucle tú mismo toma quince líneas y muestra exactamente qué sucede en cada paso, lo que ayuda cuando algo sale mal. Los resultados de las herramientas vuelven al modelo como objetos ToolMessage, que se convierten en mensajes role: "tool" en la red.
import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))
messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5): # hard cap on loop length
ai = llm_with_tools.invoke(messages)
messages.append(ai)
if not ai.tool_calls:
break
for call in ai.tool_calls:
result = tools[call["name"]].invoke(call["args"])
messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))
print(ai.content)
Nota el range(5). Un agente sin un límite de pasos puede buclear eternamente en un resultado de herramienta confuso, y cada pasada cuesta tokens de entrada para toda la conversación hasta ahora. Cinco es un límite razonable para tareas simples; súbelo deliberadamente.
Usando el auxiliar de agente preconstruido
Las versiones recientes de LangChain incluyen un auxiliar que ejecuta este bucle por ti. El nombre y la ruta de importación han cambiado entre versiones, así que confírmalos contra la documentación de la versión instalada. En la línea 1.x actual se ve así:
import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)
Usa el auxiliar cuando quieras el patrón estándar, y el bucle escrito a mano cuando necesites reglas de parada personalizadas, registro por paso, o resultados de herramientas que quieras filtrar antes de que el modelo los vea.
Salida estructurada con modo JSON
Los agentes a menudo necesitan pasar datos a otro código, como un plan, una clasificación o una lista de campos extraídos. El modo JSON obliga a que la respuesta sea un objeto JSON válido. En LangChain puedes pasarlo a través de bind:
import json
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Extract the city and country from: 'I moved to Lyon, France last spring.' "
"Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))
Menciona la palabra JSON en el prompt y describe las claves que esperas, como en el ejemplo. El modo JSON garantiza la sintaxis, no tu esquema, así que aún valida el objeto analizado (con Pydantic, por ejemplo) y maneja una clave faltante.
Límites, streaming y costo para ejecuciones de agente
Los agentes realizan muchas llamadas en poco tiempo, por lo que los límites de la cuenta importan más que para un chatbot simple. Una clave completa permite 8 peticiones simultáneas y 300 peticiones por minuto. Una clave de prueba permite 2 y 60. Si distribuyes con batch o ejecutas varios agentes a la vez, limita el paralelismo en la configuración:
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
print(a.content)
Usa 2 en lugar de 8 en la clave de prueba. Para agentes interactivos, llm.stream(...) devuelve tokens por SSE a medida que se generan, y los números de uso llegan al final del streaming.
Estimar el coste es fácil. Una ejecución de 5 pasos que promedia 4.000 tokens de entrada y 300 de salida por paso usa 20.000 tokens de entrada y 1.500 de salida en total, lo que son $0,003 + $0,00075 = $0,00375 por ejecución a $0,15 y $0,50 por 1M de tokens. La página de precios tiene las tarifas, y la documentación lista los parámetros y cabeceras de la petición, incluyendo X-Request-Id para rastrear una única llamada fallida.
Diseñando herramientas que el modelo puede usar
La mayoría de los fallos de agente se remontan a las herramientas, no al bucle. Algunas reglas ayudan con cualquier modelo:
- Mantén cada herramienta estrecha. Una herramienta llamada
get_order_statusfunciona mejor que una llamadadatabase_queryque toma texto de formato libre. - Usa tipos de argumentos simples: cadenas, enteros y enumeraciones cortas. Los objetos profundamente anidados dan al modelo más formas de equivocarse en un campo.
- Devuelve resultados cortos y simples. Una herramienta que vuelca 50.000 caracteres en la conversación llena la ventana de contexto y aumenta el costo de cada paso posterior.
- Devuelve errores como texto, como "order_id debe parecerse a A100", en lugar de lanzar excepciones que terminen la ejecución.
Prueba el agente con un puñado de prompts reales con el crédito de prueba de $0,50 antes de escalar. Los nuevos usuarios lo obtienen con un clic en la página de claves, y es válido durante 7 días.
Errores a verificar primero
- Nunca aparece la llamada a herramienta. Haz que el docstring sea específico, baja la temperatura o fuerza la llamada con
tool_choice. - Argumentos inválidos. Valida dentro de la herramienta y devuelve una cadena de error clara, para que el modelo pueda corregirse en el siguiente paso.
- Crecimiento del contexto. La ventana es de 100.000 tokens incluyendo la respuesta. Recorta la salida de herramientas antigua antes de que llene la ventana.
Más guías
Preguntas y respuestas
¿Qué clase de LangChain funciona con esta API?
ChatOpenAI de langchain-openai. Establece base_url a https://api.unlimitedaiapi.com/v1, modelo a uncensored y pasa tu clave como api_key.
¿La API admite llamadas a funciones para agentes?
Sí. Acepta los parámetros tools y tool_choice, devuelve tool_calls (también en streaming) y acepta los resultados como mensajes con role tool.
¿Puede LangChain analizar salida estructurada a través de esta API?
Sí, mediante el modo JSON: establece response_format a un tipo json_object. Garantiza sintaxis JSON válida, así que valida los campos tú mismo.
¿Cuántos agentes puedo ejecutar en paralelo?
Una clave completa permite 8 peticiones simultáneas y 300 por minuto. La clave de prueba permite 2 simultáneas y 60 por minuto.
Tu clave está a un formulario de distancia
Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.