API Agenti (Beta)

LibreChat espone i tuoi agenti attraverso due interfacce compatibili con le API, consentendo ad applicazioni, script e servizi esterni di interagire con i tuoi agenti in modo programmatico.

Panoramica

L'API Agents fornisce due interfacce:

• Chat Completions compatibili con OpenAI — POST /api/agents/v1/chat/completions
• API Risposte Aperte — POST /api/agents/v1/responses

Entrambi sono autenticati tramite chiavi API e supportano risposte in streaming, rendendo semplice l'integrazione degli agenti LibreChat nei flussi di lavoro esistenti che utilizzano già SDK OpenAI o strumenti simili.

LibreChat sta adottando Open Responses come framework API principale per gestire gli agenti. Sebbene l'endpoint Chat Completions fornisca compatibilità con le versioni precedenti per gli strumenti compatibili con OpenAI, l'endpoint Open Responses rappresenta la direzione futura.

Abilitazione dell'API Agents

L'API Agents è protetta dietro la configurazione dell'interfaccia remoteAgents. Tutte le autorizzazioni sono impostate su false per impostazione predefinita.

interface:
  remoteAgents:
    use: true
    create: true

Vedi Interface Configuration — remoteAgents per tutte le opzioni disponibili.

Nota: Gli utenti amministratori hanno tutti i permessi di agente remoto abilitati per impostazione predefinita.

Gestione delle API Key

Una volta abilitati remoteAgents.use e remoteAgents.create, gli utenti possono generare chiavi API dall'interfaccia utente di LibreChat. Queste chiavi autenticano le richieste all'API degli Agent.

Autenticazione

L'API Agents supporta due metodi di autenticazione che possono essere utilizzati indipendentemente o insieme.

Chiave API

L'autenticazione tramite API key è abilitata per impostazione predefinita. Genera le API key dall'interfaccia utente di LibreChat una volta che remoteAgents.use e remoteAgents.create sono stati abilitati.

Authorization: Bearer <YOUR_API_KEY>

OIDC Bearer Token

Per scenari machine-to-machine in cui la tua infrastruttura dispone già di un provider OIDC, puoi autenticarti direttamente con token Bearer OIDC senza una chiave API di LibreChat.

Configura l'autenticazione OIDC in 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

Quindi chiama l'API con il tuo token di accesso 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!"}'

Vedi Agents Endpoint - remoteApi per tutte le opzioni di configurazione.

Endpoint

Chat Completions (compatibile con OpenAI)

POST /api/agents/v1/chat/completions

Utilizza qualsiasi SDK compatibile con OpenAI puntandolo alla tua istanza LibreChat. Il parametro model corrisponde a un ID agente.

Esempio 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
  }'

Esempio con OpenAI SDK (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="")

Elenco modelli

GET /api/agents/v1/models

Restituisce gli agenti disponibili come modelli. Utile per scoprire quali agenti sono accessibili con la tua API key.

API per le risposte aperte

POST /api/agents/v1/responses

L'endpoint Open Responses segue la specifica Open Responses, uno standard di inferenza aperto avviato da OpenAI e costruito dalla comunità AI open-source. È progettato per flussi di lavoro agentici con supporto nativo per ragionamento, utilizzo di strumenti, output strutturati ed eventi semantici in streaming.

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?"
  }'

Monitoraggio dell'utilizzo dei token

Tutte le richieste alle API degli Agent tracciano l'utilizzo dei token rispetto al saldo dell'utente (quando la spesa dei token è configurata). Vengono conteggiati sia i token di input che quelli di output, inclusi i token di cache per i provider che li supportano (OpenAI, Anthropic).

Roadmap

• Open Responses come interfaccia principale — Abbiamo in programma di espandere l'endpoint Open Responses con il supporto completo per cicli agentici, orchestrazione di strumenti ed eventi semantici in streaming.
• Anthropic Messages API — Potremmo aggiungere in futuro il supporto per il formato Anthropic Messages API come interfaccia aggiuntiva.

Documentazione correlata

• Agents — Creazione e configurazione di agenti
• Configurazione dell'interfaccia — remoteAgents — Impostazioni di controllo dell'accesso
• Utilizzo dei token — Configurazione della spesa e del saldo dei token
• Open Responses Specification — Lo standard di inferenza aperto