LangChain y LangGraph sin clave de API

Qué puede significar «sin clave de API» en la práctica

Buscar langchain y langraph sin api key suele significar una de tres cosas. Quizás quieras evitar pagar antes de saber si el stack funciona. Quizás no quieras entregar una tarjeta de crédito a otro proveedor más. O quizás esperes ejecutar un grafo de agentes sin ninguna credencial.

El tercer deseo no puede ser satisfecho por ningún servicio alojado: un servidor que realiza el trabajo por ti debe saber quién lo está llamando. Lo que puedes obtener es una clave que no cuesta nada y no pide tarjeta. Los nuevos usuarios en este sitio pueden obtener $0.50 de crédito de prueba con un clic en la página de clave de API después de iniciar sesión con Google o con un correo electrónico y contraseña. Es una por persona y válida por 7 días.

La otra ruta hacia «sin clave» es un modelo local servido por algo en tu propia máquina. Eso funciona, pero asumes el hardware, y un portátil no igualará un endpoint alojado para ejecuciones de agentes largas. Una prueba alojada es la forma más rápida de saber si la lógica de tu grafo es sólida, y el código que escribes es idéntico a lo que ejecutarás más tarde con una clave financiada.

Como el endpoint es compatible con OpenAI, LangChain no necesita una integración especial. Apuntas su clase de chat de OpenAI a una base URL diferente, le das la clave y nombras el modelo uncensored. Todo lo que sigue asume esa configuración.

Paso 1: obtener la clave de prueba y configurar el entorno

Regístrate, abre la página de claves y presiona el botón de prueba. Copia la clave y mantenla fuera de tu repositorio. Ponla en una variable de entorno para que el mismo script funcione con una clave de prueba hoy y con una clave completa más tarde.

Copyexport UNCENSORED_API_KEY="paste-your-key-here"
pip install -U langchain-openai langgraph langchain-core

Antes de involucrar cualquier framework, verifica la clave con una petición simple. Dos minutos aquí ahorran una hora de leer trazas de pila que en realidad son errores de autenticación.

Copycurl https://api.stableaudio.top/v1/chat/completions \
  -H "Authorization: Bearer $UNCENSORED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with one word: ready"}]}'

Una llamada GET /v1/models es la otra verificación rápida; debería listar uncensored. La clave de prueba permite 2 solicitudes concurrentes y 60 solicitudes por minuto, lo cual es suficiente para desarrollar un grafo, pero vale la pena tenerlo en cuenta cuando añadas nodos en paralelo.

Paso 2: apuntar LangChain al endpoint

La clase a usar es ChatOpenAI de langchain-openai. Dos argumentos hacen el trabajo: base_url y api_key. El nombre del modelo es uncensored, y las configuraciones habituales de muestreo se pasan tal cual.

Copyimport os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.stableaudio.top/v1",
    api_key=os.environ["UNCENSORED_API_KEY"],
    temperature=0.7,
    max_retries=3,
)

print(llm.invoke("Give me three titles for an ambient track about rain.").content)

Si esto imprime texto, la conexión es buena. El streaming funciona de la misma manera: itera sobre llm.stream(...) y los fragmentos llegan mediante eventos enviados por el servidor, con el uso reportado al final del stream.

Un error común es dejar la variable OPENAI_API_KEY configurada de un proyecto antiguo. LangChain enviará felizmente ese valor a tu base URL personalizada si olvidas pasar api_key. Pasa la clave explícitamente y eliminas la conjetura.

Paso 3: un grafo mínimo de LangGraph

LangGraph modela tu agente como un estado que se mueve entre nodos. El grafo útil más pequeño tiene un nodo que llama al modelo y adjunta la respuesta a una lista de mensajes. MessagesState te da esa lista gratis.

Copyfrom langgraph.graph import StateGraph, MessagesState, START, END

def call_model(state: MessagesState):
    reply = llm.invoke(state["messages"])
    return {"messages": [reply]}

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_edge(START, "model")
builder.add_edge("model", END)
graph = builder.compile()

out = graph.invoke({"messages": [("user", "Outline a three-act short story about a lighthouse keeper.")]})
print(out["messages"][-1].content)

Esto es deliberadamente simple. El punto es que nada en LangGraph sabe o le importa qué proveedor se encuentra detrás de llm. Cualquier nodo puede tomar un objeto de modelo diferente, por lo que luego puedes dar a un paso de planificación barato y un paso de escritura más largo sus propias configuraciones, como una temperatura más baja para la planificación.

Paso 4: agregar herramientas y un bucle

Los agentes se vuelven interesantes cuando el modelo puede realizar llamadas a herramientas. El endpoint admite el uso de tools y tool_choice, y los resultados de las herramientas se devuelven como mensajes role: "tool". LangChain y LangGraph gestionan esa infraestructura por ti.

Copyfrom langchain_core.tools import tool
from langgraph.prebuilt import ToolNode, tools_condition

@tool
def word_count(text: str) -> int:
    'Count the words in a piece of text.'
    return len(text.split())

tools = [word_count]
llm_with_tools = llm.bind_tools(tools)

def agent(state: MessagesState):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

builder = StateGraph(MessagesState)
builder.add_node("agent", agent)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)
builder.add_edge("tools", "agent")
graph = builder.compile()

result = graph.invoke({"messages": [("user", "Write a 40-word product blurb, then check its word count with the tool.")]})
print(result["messages"][-1].content)

El bucle es la idea completa: el nodo del agente responde, tools_condition verifica si la respuesta pidió una herramienta, el nodo de herramienta la ejecuta, y el control vuelve al agente. Cuando una respuesta no tiene llamada a herramienta, el grafo termina.

Los modelos de pesos abiertos varían en qué tan limpios son sus argumentos de herramienta. Si una llamada vuelve malformada, ajusta la docstring de la herramienta, baja la temperatura y mantén el esquema de argumentos pequeño. Los esquemas cortos y tipados fallan menos que los largos con muchos campos opcionales.

Límites de peticiones, reintentos y ramas paralelas

El punto donde los grafos de agentes suelen tener problemas es la concurrencia. Una clave completa permite 8 solicitudes concurrentes y 300 solicitudes por minuto; una clave de prueba permite 2 y 60. Si tu grafo se ramifica en cinco nodos paralelos con una clave de prueba, tres de ellos se rechazarán con HTTP 429 y el código de error concurrency. Superar el límite por minuto devuelve rate_limited. Una sobrecarga temporal también devuelve un 429, con un encabezado Retry-After: 5.

Tres hábitos mantienen esto manejable:

• Mantén max_retries en 2 o 3 en ChatOpenAI para que los 429 cortos se reintenten con retroceso.
• Limita la ramificación a tu límite de concurrencia. En LangGraph puedes pasar config={"max_concurrency": 2} al invocar el grafo.
• Recuerda que una petición en streaming mantiene su espacio hasta que el stream termine, por lo que un consumidor lento mantiene un espacio ocupado.

Copyout = graph.invoke(
    {"messages": [("user", "Draft five taglines in parallel.")]},
    config={"max_concurrency": 2},
)

Los encabezados de respuesta ayudan con la depuración. X-Request-Id identifica una llamada si necesitas preguntar a soporte sobre ella, y X-Balance-USD muestra tu crédito restante después de cada petición.

Lista de verificación para depurar cuando el grafo se comporta mal

La mayoría de los fallos en un primer proyecto de LangGraph no tienen que ver con el modelo. Vienen de la configuración, y una lista de verificación corta captura casi todos ellos.

1. Errores 401 o de autenticación. Falta la clave, está mal escrita o se está leyendo una OPENAI_API_KEY antigua. Imprime los primeros cuatro caracteres del valor que realmente usa tu script.
2. 404 o modelo no encontrado. El nombre del modelo debe ser uncensored. Llama a GET /v1/models si no estás seguro de qué lista el endpoint.
3. Errores de conexión. La base URL debe terminar en /v1 y no debe incluir /chat/completions; el cliente añade esa parte.
4. Bucles infinitos. Si el agente sigue llamando a una herramienta, el valor de retorno de esta puede no responder la pregunta. Devuelve cadenas simples y cortas y establece un límite de recursión a través de la configuración del grafo para que un mal bucle se detenga antes.
5. Respuestas vacías o extrañas. Imprime la lista completa de mensajes después de una ejecución. A menudo un nodo anterior escribió un mensaje del sistema que contradice el posterior.

Cuando una petición falla en el lado del servidor, cita el encabezado X-Request-Id en tu mensaje a soporte. Esto les permite encontrar esa llamada exacta sin conjeturas. Ten en cuenta también que las peticiones fallidas o rechazadas no se cobran, por lo que una sesión de depuración llena de errores no consume tu crédito de prueba.

Un punto de diseño más. Dale a cada nodo un trabajo estrecho y un prompt corto. Un grafo con un planificador, un escritor y un verificador, cada uno con su propio mensaje del sistema pequeño, es más fácil de probar que un solo nodo con una página de instrucciones, y cada pieza puede probarse sola con una llamada directa llm.invoke antes de conectarla.

Lo que realmente cuesta una ejecución de prueba

La tarifa es de $0.15 por 1M de tokens de entrada y $0.50 por 1M de tokens de salida, desde el crédito prepago. Las peticiones fallidas o rechazadas no se cobran. Los grafos de agentes llaman al modelo varias veces por tarea, y cada llamada reenvía la lista de mensajes en crecimiento, por lo que los tokens de entrada dominan.

Realiza una ejecución con seis llamadas al modelo. Digamos que cada llamada envía 3.000 tokens y devuelve 400 tokens. Eso son 18.000 tokens de entrada y 2.400 tokens de salida.

• Entrada: 18.000 / 1.000.000 x $0.15 = $0.0027
• Salida: 2.400 / 1.000.000 x $0.50 = $0.0012
• Total: $0.0039 por ejecución

Los $0.50 de prueba divididos por $0.0039 son aproximadamente 128 ejecuciones de ese tamaño, suficientes para construir y probar un grafo adecuadamente. Cuando superes ese límite, las recargas van desde $20 hasta $500 en cantidades enteras, con un bono del 5% desde $50, 10% desde $100 y 15% desde $200; la página de precios tiene los detalles. Puedes pagar con tarjeta (Visa, Mastercard, Apple Pay, Google Pay) o con criptomonedas (USDT en TRC20, USDC en Base). El crédito no caduca y los prompts no se usan para entrenamiento.

La ventana de contexto es de 100.000 tokens para prompt más completion, por lo que las historias largas de agentes caben, pero pagas por cada token que reenvías. Recortar mensajes antiguos con las utilidades de mensajes de LangGraph mantiene el costo y la latencia bajos. Para el formato de petición crudo detrás de todo esto, consulta la documentación de la API.

Más guías

• LLM de texto a audio: qué puede y qué no puede hacer
• API de texto sin censura para prompts de vídeo