API de Agentes (Beta)

O LibreChat expõe seus agentes através de duas interfaces compatíveis com API, permitindo que aplicações, scripts e serviços externos interajam com seus agentes de forma programática.

Visão geral

A API de Agents fornece duas interfaces:

• Chat Completions compatíveis com OpenAI — POST /api/agents/v1/chat/completions
• API de Respostas Abertas — POST /api/agents/v1/responses

Ambos são autenticados via chaves de API e suportam respostas em streaming, tornando fácil integrar agentes do LibreChat em fluxos de trabalho existentes que já utilizam SDKs da OpenAI ou ferramentas similares.

O LibreChat está adotando Open Responses como seu framework de API principal para servir agentes. Embora o endpoint Chat Completions forneça compatibilidade retroativa com ferramentas existentes compatíveis com OpenAI, o endpoint Open Responses representa a direção futura.

Habilitando a Agents API

A Agents API está protegida pela configuração de interface remoteAgents. Todas as permissões são definidas como false por padrão.

interface:
  remoteAgents:
    use: true
    create: true

Veja Interface Configuration — remoteAgents para todas as opções disponíveis.

Nota: Usuários administradores têm todas as permissões de agente remoto habilitadas por padrão.

Gerenciamento de Chaves de API

Assim que remoteAgents.use e remoteAgents.create estiverem habilitados, os usuários poderão gerar chaves de API a partir da interface do LibreChat. Essas chaves autenticam as solicitações para a API de Agents.

Autenticação

A Agents API suporta dois métodos de autenticação que podem ser usados de forma independente ou conjunta.

Chave de API

A autenticação por chave de API está habilitada por padrão. Gere chaves de API a partir da interface do LibreChat assim que remoteAgents.use e remoteAgents.create estiverem habilitados.

Authorization: Bearer <YOUR_API_KEY>

OIDC Bearer Token

Para cenários máquina-a-máquina onde sua infraestrutura já possui um provedor OIDC, você pode autenticar diretamente com tokens OIDC Bearer sem uma chave de API do LibreChat.

Configure a autenticação OIDC no 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

Em seguida, chame a API com seu token de acesso 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!"}'

Veja Agents Endpoint - remoteApi para todas as opções de configuração.

Endpoints

Chat Completions (compatível com OpenAI)

POST /api/agents/v1/chat/completions

Use qualquer SDK compatível com OpenAI apontando-o para sua instância do LibreChat. O parâmetro model corresponde a um ID de agente.

Exemplo com 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
  }'

Exemplo com 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="")

Listar Modelos

GET /api/agents/v1/models

Retorna os agentes disponíveis como modelos. Útil para descobrir quais agentes estão acessíveis com sua chave de API.

API de Respostas Abertas

POST /api/agents/v1/responses

O endpoint Open Responses segue a especificação Open Responses, um padrão de inferência aberto iniciado pela OpenAI e construído pela comunidade de IA de código aberto. Ele foi projetado para fluxos de trabalho agenticos com suporte nativo para raciocínio, uso de ferramentas, saídas estruturadas e streaming 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?"
  }'

Rastreamento de Uso de Tokens

Todas as requisições da API de Agents rastreiam o uso de tokens em relação ao saldo do usuário (quando o consumo de tokens está configurado). Tanto os tokens de entrada quanto os de saída são contabilizados, incluindo tokens de cache para provedores que os suportam (OpenAI, Anthropic).

Roadmap

• Open Responses como interface principal — Planejamos expandir o endpoint Open Responses com suporte total para loops agenticos, orquestração de ferramentas e streaming de eventos semânticos.
• Anthropic Messages API — Podemos adicionar suporte ao formato da Anthropic Messages API como uma interface adicional no futuro.

Documentação Relacionada

• Agents — Criando e configurando agents
• Configuração da Interface — remoteAgents — Configurações de controle de acesso
• Uso de Tokens — Configurando o consumo e saldo de tokens
• Open Responses Specification — O padrão aberto de inferência