Agents API (Beta)

LibreChat aracılarına OpenAI uyumlu ve Open Responses API endpoint'leri aracılığıyla programatik olarak erişin

Beta Özelliği

Agents API şu anda beta aşamasındadır. Kararlı bir sürüme doğru ilerlerken endpoint'ler, istek/yanıt formatları ve davranışlar değişebilir.

LibreChat, ajanlarınızı iki adet API uyumlu arayüz üzerinden sunarak harici uygulamaların, betiklerin ve servislerin ajanlarınızla programatik olarak etkileşime girmesine olanak tanır.

Genel Bakış

Agents API iki arayüz sunar:

OpenAI ile uyumlu Chat Completions — POST /api/agents/v1/chat/completions
Open Responses API — POST /api/agents/v1/responses

Her ikisi de API anahtarları aracılığıyla doğrulanır ve yanıt akışını (streaming) destekler; bu da LibreChat aracılarını, halihazırda OpenAI SDK'lerini veya benzer araçları kullanan mevcut iş akışlarına entegre etmeyi kolaylaştırır.

LibreChat, ajanlara hizmet vermek için birincil API çerçevesi olarak Open Responses sistemini benimsiyor. Chat Completions endpoint'i, mevcut OpenAI uyumlu araçlarla geriye dönük uyumluluk sağlasa da, Open Responses endpoint'i gelecekteki yönü temsil etmektedir.

Agents API'sini Etkinleştirme

Agents API, remoteAgents arayüz yapılandırması ile sınırlandırılmıştır. Tüm izinler varsayılan olarak false değerindedir.

interface:
  remoteAgents:
    use: true
    create: true

Tüm mevcut seçenekler için Interface Configuration — remoteAgents bölümüne bakın.

Not: Yönetici kullanıcılar, varsayılan olarak tüm uzak aracı (remote agent) izinlerine sahiptir.

API Anahtarı Yönetimi

remoteAgents.use ve remoteAgents.create özellikleri etkinleştirildiğinde, kullanıcılar LibreChat arayüzünden API anahtarları oluşturabilirler. Bu anahtarlar, Agents API'sine yapılan isteklerin kimlik doğrulamasını sağlar.

Kimlik Doğrulama

Agents API, bağımsız olarak veya birlikte kullanılabilen iki kimlik doğrulama yöntemini destekler.

API Anahtarı

API anahtarı kimlik doğrulaması varsayılan olarak etkindir. remoteAgents.use ve remoteAgents.create etkinleştirildikten sonra LibreChat arayüzünden API anahtarları oluşturun.

Authorization: Bearer <YOUR_API_KEY>

OIDC Bearer Token

Altyapınızın halihazırda bir OIDC sağlayıcısına sahip olduğu makineden makineye senaryolar için, bir LibreChat API anahtarı olmadan doğrudan OIDC Bearer token'ları ile kimlik doğrulaması yapabilirsiniz.

librechat.yaml içinde OIDC kimlik doğrulamasını yapılandırın:

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

Ardından OIDC erişim belirtecinizle (access token) API'yi çağırın:

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

OIDC belirteci, LibreChat içinde halihazırda var olan bir kullanıcıya ait olmalıdır. Eşleştirme işlemi önce sub talebini kullanır, ardından sırasıyla email, preferred_username veya upn değerlerine başvurur.

Tüm yapılandırma seçenekleri için Agents Endpoint - remoteApi bölümüne bakın.

Endpoints

Chat Completions (OpenAI-compatible)

POST /api/agents/v1/chat/completions

LibreChat örneğinizi işaret ederek herhangi bir OpenAI uyumlu SDK kullanın. model parametresi bir aracı (agent) kimliğine karşılık gelir.

curl ile örnek:

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

OpenAI SDK (Python) ile örnek:

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

Modelleri Listele

GET /api/agents/v1/models

Mevcut ajanları modeller olarak döndürür. API anahtarınızla hangi ajanlara erişilebileceğini keşfetmek için kullanışlıdır.

Open Responses API

POST /api/agents/v1/responses

Open Responses endpoint'i, OpenAI tarafından başlatılan ve açık kaynaklı yapay zeka topluluğu tarafından oluşturulan bir açık çıkarım standardı olan Open Responses specification ile uyumludur. Akıl yürütme, araç kullanımı, yapılandırılmış çıktılar ve akış halindeki anlamsal olaylar için yerel destekle birlikte, etmen tabanlı (agentic) iş akışları için tasarlanmıştır.

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

Token Kullanım Takibi

Tüm Agents API istekleri, (token harcaması yapılandırıldığında) kullanıcının bakiyesine göre token kullanımını takip eder. Hem giriş hem de çıkış tokenları, bunları destekleyen sağlayıcılar (OpenAI, Anthropic) için önbellek (cache) tokenları da dahil olmak üzere sayılır.

Yol Haritası

Open Responses birincil arayüz olarak — Open Responses endpoint'ini; agentic döngüler, araç düzenleme (tool orchestration) ve akış halindeki anlamsal olaylar (streaming semantic events) için tam destekle genişletmeyi planlıyoruz.
Anthropic Messages API — Gelecekte ek bir arayüz olarak Anthropic Messages API formatı için destek ekleyebiliriz.

Agents — Ajan oluşturma ve yapılandırma
Arayüz Yapılandırması — remoteAgents — Erişim denetimi ayarları
Token Usage — Token harcamasını ve bakiyesini yapılandırma
Open Responses Specification — Açık çıkarım standardı

Agents API (Beta)

Bu sayfada