API Agents (Beta)

LibreChat cung cấp các tác nhân của bạn thông qua hai giao diện tương thích với API, cho phép các ứng dụng, tập lệnh và dịch vụ bên ngoài tương tác với các tác nhân của bạn theo chương trình.

Tổng quan

Agents API cung cấp hai giao diện:

• Hoàn tất trò chuyện tương thích với OpenAI — POST /api/agents/v1/chat/completions
• API Phản hồi Mở — POST /api/agents/v1/responses

Cả hai đều được xác thực thông qua API keys và hỗ trợ phản hồi dạng streaming, giúp việc tích hợp các tác nhân LibreChat vào các quy trình làm việc hiện có đang sử dụng OpenAI SDK hoặc các công cụ tương tự trở nên dễ dàng.

LibreChat đang áp dụng Open Responses làm khung API chính để phục vụ các tác nhân (agents). Mặc dù endpoint Chat Completions cung cấp khả năng tương thích ngược với các công cụ tương thích với OpenAI hiện có, nhưng endpoint Open Responses đại diện cho định hướng phát triển trong tương lai.

Kích hoạt Agents API

Agents API được bảo vệ bởi cấu hình giao diện remoteAgents. Tất cả các quyền mặc định được đặt thành false.

interface:
  remoteAgents:
    use: true
    create: true

Xem Interface Configuration — remoteAgents để biết tất cả các tùy chọn khả dụng.

Lưu ý: Người dùng quản trị viên (Admin) được mặc định bật tất cả các quyền của tác nhân từ xa (remote agent).

Quản lý API Key

Khi remoteAgents.use và remoteAgents.create được bật, người dùng có thể tạo khóa API từ giao diện người dùng LibreChat. Các khóa này xác thực các yêu cầu gửi đến Agents API.

Xác thực

Agents API hỗ trợ hai phương thức xác thực có thể được sử dụng độc lập hoặc kết hợp với nhau.

API Key

Xác thực bằng API key được bật theo mặc định. Hãy tạo API key từ giao diện người dùng LibreChat sau khi remoteAgents.use và remoteAgents.create đã được kích hoạt.

Authorization: Bearer <YOUR_API_KEY>

OIDC Bearer Token

Đối với các kịch bản máy-với-máy (machine-to-machine) nơi cơ sở hạ tầng của bạn đã có sẵn nhà cung cấp OIDC, bạn có thể xác thực trực tiếp bằng mã thông báo OIDC Bearer mà không cần khóa API LibreChat.

Cấu hình xác thực OIDC trong 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

Sau đó, hãy gọi API bằng OIDC access token của bạ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!"}'

Xem Agents Endpoint - remoteApi để biết tất cả các tùy chọn cấu hình.

Endpoints

Chat Completions (tương thích với OpenAI)

POST /api/agents/v1/chat/completions

Sử dụng bất kỳ SDK tương thích với OpenAI nào bằng cách trỏ nó đến instance LibreChat của bạn. Tham số model tương ứng với một ID tác nhân (agent ID).

Ví dụ với 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
  }'

Ví dụ với 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="")

Liệt kê các Model

GET /api/agents/v1/models

Trả về các agent khả dụng dưới dạng model. Hữu ích để khám phá những agent nào có thể truy cập được bằng API key của bạn.

API Phản hồi Mở (Open Responses API)

POST /api/agents/v1/responses

Endpoint Open Responses tuân theo đặc tả Open Responses, một tiêu chuẩn suy luận mở được khởi xướng bởi OpenAI và được xây dựng bởi cộng đồng AI mã nguồn mở. Nó được thiết kế cho các quy trình làm việc tác nhân (agentic workflows) với sự hỗ trợ gốc cho suy luận, sử dụng công cụ, đầu ra có cấu trúc và truyền phát các sự kiện ngữ nghĩa.

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

Theo dõi mức sử dụng Token

Tất cả các yêu cầu API của Agents đều theo dõi mức sử dụng token dựa trên số dư của người dùng (khi tính năng chi tiêu token được cấu hình). Cả token đầu vào và đầu ra đều được tính, bao gồm cả các token bộ nhớ đệm (cache tokens) đối với các nhà cung cấp hỗ trợ tính năng này (OpenAI, Anthropic).

Lộ trình

• Open Responses làm giao diện chính — Chúng tôi dự định mở rộng endpoint Open Responses với sự hỗ trợ đầy đủ cho các vòng lặp tác tử (agentic loops), điều phối công cụ (tool orchestration) và truyền phát các sự kiện ngữ nghĩa (streaming semantic events).
• Anthropic Messages API — Chúng tôi có thể sẽ thêm hỗ trợ cho định dạng Anthropic Messages API như một giao diện bổ sung trong tương lai.

Tài liệu liên quan

• Agents — Tạo và cấu hình các agent
• Cấu hình giao diện — remoteAgents — Các thiết lập kiểm soát truy cập
• Token Usage — Cấu hình chi tiêu và số dư token
• Open Responses Specification — Tiêu chuẩn suy luận mở