API de agentes (Beta)

LibreChat expone tus agentes a través de dos interfaces compatibles con API, lo que permite que aplicaciones, scripts y servicios externos interactúen con tus agentes de forma programática.

Descripción general

La API de Agents proporciona dos interfaces:

• Chat Completions compatibles con OpenAI — POST /api/agents/v1/chat/completions
• API de respuestas abiertas — POST /api/agents/v1/responses

Ambos se autentican mediante API keys y admiten respuestas en streaming, lo que facilita la integración de agentes de LibreChat en flujos de trabajo existentes que ya utilizan SDKs de OpenAI o herramientas similares.

LibreChat está adoptando Open Responses como su framework de API principal para servir agentes. Si bien el endpoint Chat Completions proporciona compatibilidad con versiones anteriores para herramientas existentes compatibles con OpenAI, el endpoint Open Responses representa la dirección futura.

Habilitación de la Agents API

La API de Agents está protegida detrás de la configuración de interfaz remoteAgents. Todos los permisos están configurados de forma predeterminada en false.

interface:
  remoteAgents:
    use: true
    create: true

Consulta Interface Configuration — remoteAgents para ver todas las opciones disponibles.

Nota: Los usuarios administradores tienen todos los permisos de agente remoto habilitados de forma predeterminada.

Gestión de API Key

Una vez que remoteAgents.use y remoteAgents.create estén habilitados, los usuarios pueden generar claves de API desde la interfaz de usuario de LibreChat. Estas claves autentican las solicitudes a la API de Agents.

Autenticación

La API de Agents admite dos métodos de autenticación que pueden utilizarse de forma independiente o conjunta.

Clave de API

La autenticación mediante API key está habilitada de forma predeterminada. Genera API keys desde la interfaz de usuario de LibreChat una vez que remoteAgents.use y remoteAgents.create estén habilitados.

Authorization: Bearer <YOUR_API_KEY>

Token de portador OIDC

Para escenarios de máquina a máquina donde su infraestructura ya cuenta con un proveedor OIDC, puede autenticarse directamente con tokens Bearer OIDC sin necesidad de una clave de API de LibreChat.

Configure la autenticación OIDC en librechat.yaml:

endpoints:
  agents:
    remoteApi:
      auth:
        apiKey:
          enabled: false
        oidc:
          enabled: true
          issuer: https://auth.example.com/realms/myrealm
          # jwksUri is optional and auto-discovered from issuer if omitted
          audience: my-client-id

Luego, llama a la API con tu token de acceso OIDC:

curl -X POST https://your-librechat-instance/api/agents/v1/responses \
  -H "Authorization: Bearer YOUR_OIDC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "agent_abc123", "input": "Hello!"}'

Consulte Agents Endpoint - remoteApi para ver todas las opciones de configuración.

Endpoints

Chat Completions (compatibles con OpenAI)

POST /api/agents/v1/chat/completions

Utilice cualquier SDK compatible con OpenAI apuntándolo a su instancia de LibreChat. El parámetro model corresponde a un ID de agente.

Ejemplo con curl:

curl -X POST https://your-librechat-instance/api/agents/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_abc123",
    "messages": [
      {"role": "user", "content": "Hello, what can you help me with?"}
    ],
    "stream": true
  }'

Ejemplo con el SDK de OpenAI (Python):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-librechat-instance/api/agents/v1",
    api_key="YOUR_API_KEY"
)

response = client.chat.completions.create(
    model="agent_abc123",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
)

for chunk in response:
    print(chunk.choices[0].delta.content, end="")

Listar modelos

GET /api/agents/v1/models

Devuelve los agentes disponibles como modelos. Útil para descubrir qué agentes son accesibles con su clave de API.

API de respuestas abiertas

POST /api/agents/v1/responses

El endpoint Open Responses sigue la especificación Open Responses, un estándar de inferencia abierto iniciado por OpenAI y construido por la comunidad de IA de código abierto. Está diseñado para flujos de trabajo de agentes con soporte nativo para razonamiento, uso de herramientas, salidas estructuradas y transmisión de eventos semánticos.

curl -X POST https://your-librechat-instance/api/agents/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent_abc123",
    "input": "What is the weather today?"
  }'

Seguimiento del uso de tokens

Todas las solicitudes a la API de Agents rastrean el uso de tokens contra el saldo del usuario (cuando el gasto de tokens está configurado). Se contabilizan tanto los tokens de entrada como los de salida, incluyendo los tokens de caché para los proveedores que los admiten (OpenAI, Anthropic).

Hoja de ruta

• Open Responses como interfaz principal — Planeamos expandir el endpoint Open Responses con soporte completo para bucles de agentes, orquestación de herramientas y transmisión de eventos semánticos.
• Anthropic Messages API — Es posible que añadamos soporte para el formato de la Anthropic Messages API como una interfaz adicional en el futuro.

Documentación relacionada

• Agents — Creación y configuración de agentes
• Configuración de la interfaz — remoteAgents — Ajustes de control de acceso
• Uso de tokens — Configuración del gasto y saldo de tokens
• Open Responses Specification — El estándar abierto de inferencia