LibreChat is joining ClickHouse to power the open-source Agentic Data Stack 🎉 Learn more
LibreChat
Cấu hìnhLibreChat YAMLCấu trúc đối tượngCấu trúc đối tượng endpoint Agents

Cấu trúc đối tượng endpoint Agents

Trang này áp dụng cho endpoint agents.

Ví dụ

endpoints:
  agents:
    recursionLimit: 50
    maxRecursionLimit: 100
    disableBuilder: false
    # (optional) Agent Capabilities available to all users. Omit the ones you wish to exclude. Defaults to list below.
    # Add "programmatic_tools" with "execute_code" to enable Programmatic Tool Calling for MCP tools.
    # capabilities: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]
    # (optional) File citation configuration for file_search capability
    maxCitations: 30 # Maximum total citations in responses (1-50)
    maxCitationsPerFile: 7 # Maximum citations from each file (1-10)
    minRelevanceScore: 0.45 # Minimum relevance score threshold (0.0-1.0)
    titleTiming: immediate
    skills:
      maxCatalogSkills: 20
    remoteApi:
      auth:
        oidc:
          enabled: false

Cấu hình này cho phép giao diện trình tạo (builder interface) cho các tác nhân (agents).

recursionLimit

KeyTypeDescriptionExample
recursionLimitNumberThiết lập số bước mặc định mà một agent có thể thực hiện trong một lần chạy.Controls recursion depth to prevent infinite loops. When limit is reached, raises GraphRecursionError. This value can be configured from the UI up to the maxRecursionLimit.

Mặc định: 25

Ví dụ:

recursionLimit: 50

Để biết thêm thông tin về các bước của tác nhân (agent steps), hãy xem Max Agent Steps.

maxRecursionLimit

KeyTypeDescriptionExample
maxRecursionLimitNumberThiết lập số bước tối đa tuyệt đối mà một agent có thể thực hiện trong một lần chạy.Defines the upper limit for the recursionLimit that can be set from the UI. This prevents users from setting excessively high values.

Mặc định: Nếu bỏ qua, giá trị mặc định sẽ là giá trị của recursionLimit hoặc 50 nếu recursionLimit cũng bị bỏ qua.

Ví dụ:

maxRecursionLimit: 100

Để biết thêm thông tin về các bước của tác nhân (agent steps), hãy xem Max Agent Steps.

titleTiming

KeyTypeDescriptionExample
titleTimingStringKiểm soát thời điểm tiêu đề cuộc trò chuyện được tạo cho endpoint agents. Các giá trị hợp lệ: "immediate" hoặc "final".Defaults to "immediate".

Mặc định: "immediate"

Các giá trị khả dụng:

  • "immediate": Tạo tiêu đề ngay khi yêu cầu bắt đầu, song song với phản hồi của model, sử dụng tin nhắn đầu tiên của người dùng.
  • "final": Trì hoãn việc tạo tiêu đề cho đến khi phản hồi hoàn tất. Điều này bảo toàn hành vi cũ.

Ví dụ:

titleTiming: immediate

disableBuilder

KeyTypeDescriptionExample
disableBuilderBooleanKiểm soát khả năng hiển thị và việc sử dụng giao diện trình tạo cho các tác nhân (agents).When set to `true`, disables the builder interface for the agent, limiting direct manual interaction.

Mặc định: false

Ví dụ:

disableBuilder: false

allowedProviders

KeyTypeDescriptionExample
allowedProvidersArray/List of StringsChỉ định danh sách các nhà cung cấp endpoint (ví dụ: "openAI", "anthropic", "google") được phép sử dụng với tính năng Agents.If defined, only agents configured with these providers can be initialized. If omitted or empty, all configured providers are allowed.

Mặc định: [] (danh sách trống, cho phép tất cả các nhà cung cấp)

Lưu ý: Phải là một trong các giá trị sau, hoặc tên endpoint tùy chỉnh như được định nghĩa trong cấu hình của bạn: - openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock

Ví dụ:

allowedProviders:
  - openAI
  - google

capabilities

KeyTypeDescriptionExample
capabilitiesArray/List of StringsChỉ định các khả năng của tác nhân (agent) khả dụng cho tất cả người dùng đối với endpoint agents.Defines the agent capabilities that are available to all users for the agents endpoint. You can omit the capabilities you wish to exclude from the list.

Mặc định: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]

Programmatic Tool Calling là tính năng tùy chọn. Chỉ thêm programmatic_tools cùng với execute_code khi quá trình triển khai Code Interpreter của bạn bao gồm thành phần Tool Call Server.

Ví dụ:

capabilities:
  - 'deferred_tools'
  # Optional: enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder.
  # Requires execute_code and a Code Interpreter deployment with the Tool Call Server component.
  # - 'programmatic_tools'
  - 'execute_code'
  - 'file_search'
  - 'web_search'
  - 'artifacts'
  - 'subagents'
  - 'actions'
  - 'context'
  - 'skills'
  - 'tools'
  - 'chain'
  - 'ocr'

Lưu ý: Trường này là tùy chọn. Nếu bỏ qua, hành vi mặc định là bao gồm tất cả các khả năng được liệt kê trong phần mặc định.

skills

Kiểm soát các cài đặt Skills ở cấp độ endpoint cho các agent.

KeyTypeDescriptionExample
skills.maxCatalogSkillsNumberGiới hạn số lượng Skill khả dụng đang hoạt động được hiển thị trong danh mục mà mô hình có thể truy cập. Phải nằm trong khoảng từ 1 đến 100.maxCatalogSkills: 20

Mặc định: Không có giới hạn nào được cấu hình ngoài giới hạn danh mục thời gian chạy.

Ví dụ:

skills:
  maxCatalogSkills: 20

Điều này không vô hiệu hóa Skills. Hãy sử dụng khả năng skills và phạm vi kỹ năng theo từng agent/model-spec để kiểm soát việc liệu Skills có khả dụng hay không.

maxCitations

KeyTypeDescriptionExample
maxCitationsNumberKiểm soát tổng số trích dẫn tối đa có thể được bao gồm trong một phản hồi của agent.When using file_search capability, limits the total number of source citations returned to prevent overwhelming responses while ensuring comprehensive coverage.

Mặc định: 30

Phạm vi: 1-50

Ví dụ:

maxCitations: 30

maxCitationsPerFile

KeyTypeDescriptionExample
maxCitationsPerFileNumberGiới hạn số lượng trích dẫn tối đa có thể được trích xuất từ bất kỳ tệp đơn lẻ nào.Ensures citation diversity by preventing any single file from dominating the citations, encouraging representation from multiple sources.

Mặc định: 7

Phạm vi: 1-10

Ví dụ:

maxCitationsPerFile: 7

minRelevanceScore

KeyTypeDescriptionExample
minRelevanceScoreNumberĐặt ngưỡng điểm liên quan tối thiểu để các nguồn được bao gồm trong phản hồi.Filters out low-quality matches based on vector similarity scores. Higher values (e.g., 0.7) ensure only highly relevant sources are cited, while lower values (e.g., 0.0) include all sources regardless of quality.

Mặc định: 0.45 (ngưỡng liên quan 45%)

Phạm vi: 0.0-1.0

Ví dụ:

minRelevanceScore: 0.45

Các ví dụ về cấu hình trích dẫn tệp

Cấu hình mặc định (Cân bằng)

endpoints:
  agents:
    maxCitations: 30
    maxCitationsPerFile: 7
    minRelevanceScore: 0.45

Cung cấp các trích dẫn toàn diện trong khi vẫn ngăn chặn các phản hồi quá tải và lọc bỏ các kết quả khớp chất lượng thấp.

Cấu hình nghiêm ngặt (Chất lượng cao)

endpoints:
  agents:
    maxCitations: 10
    maxCitationsPerFile: 3
    minRelevanceScore: 0.7

Chỉ bao gồm các trích dẫn có độ liên quan cao với các giới hạn nghiêm ngặt để có phản hồi tập trung.

Cấu hình toàn diện (Nghiên cứu)

endpoints:
  agents:
    maxCitations: 50
    maxCitationsPerFile: 10
    minRelevanceScore: 0.0

Trích xuất thông tin tối đa cho các tác vụ nghiên cứu chuyên sâu, bao gồm tất cả các nguồn bất kể mức độ liên quan.

Khả năng của Agent

Trường capabilities cho phép bạn bật hoặc tắt các chức năng cụ thể cho các tác nhân (agents). Các khả năng khả dụng bao gồm:

  • deferred_tools: Cho phép các agent khám phá các MCP tool bị trì hoãn (deferred) tại thời điểm chạy thay vì tải mọi tool vào ngữ cảnh ngay từ đầu.
  • programmatic_tools: Cho phép Gọi Công cụ Lập trình (Programmatic Tool Calling) đối với các công cụ MCP được đánh dấu là Programmatic trong Agent Builder. Yêu cầu execute_code và một triển khai Code Interpreter với thành phần Tool Call Server. Tính năng này là tùy chọn và không được bật theo mặc định.
  • execute_code: Cho phép tác nhân (agent) thực thi mã.
  • file_search: Cho phép agent tìm kiếm và tương tác với các tệp tin. Khi được bật, hành vi trích dẫn sẽ được kiểm soát bởi các cài đặt maxCitations, maxCitationsPerFile và minRelevanceScore.
  • web_search: Kích hoạt chức năng tìm kiếm web cho các tác nhân (agents), cho phép chúng tìm kiếm và truy xuất thông tin từ internet.
  • artifacts: Cho phép tác nhân tạo ra các artifacts tương tác (các thành phần React, HTML, sơ đồ Mermaid).
  • subagents: Cho phép chạy các agent con trong ngữ cảnh biệt lập. Xem Subagents.
  • actions: Cho phép tác nhân thực hiện các hành động được xác định trước.
  • context: Kích hoạt chức năng "Upload as Text" (Tải lên dưới dạng văn bản) trong trò chuyện và "File Context" (Ngữ cảnh tệp) cho các tác nhân (agents), cho phép người dùng tải lên các tệp tin để nội dung của chúng được trích xuất và đưa trực tiếp vào cuộc trò chuyện.
  • skills: Kích hoạt Skills trong bảng điều khiển bên, gọi thủ công bằng $, các kỹ năng do model gọi và danh sách cho phép kỹ năng của agent. Xem Skills.
  • tools: Cấp cho tác nhân quyền truy cập vào các công cụ khác nhau.
  • chain: Kích hoạt tính năng Beta cho việc tạo chuỗi tác nhân (agent chaining), còn được gọi là quy trình làm việc Mixture-of-Agents (MoA).
  • ocr: Tùy chọn nâng cao tính năng "Tải lên dưới dạng văn bản" (Upload as Text) trong trò chuyện và "Ngữ cảnh tệp" (File Context) cho các tác nhân (agents), cho phép tải tệp lên và xử lý bằng OCR. Yêu cầu phải cấu hình một dịch vụ OCR.

Bằng cách chỉ định các capabilities, bạn có thể kiểm soát các tính năng khả dụng cho người dùng khi tương tác với các agent.

Cấu hình ví dụ

Dưới đây là ví dụ về cách cấu hình endpoint agents với các khả năng tùy chỉnh và cài đặt trích dẫn tệp:

endpoints:
  agents:
    disableBuilder: false
    # File citation configuration
    maxCitations: 20
    maxCitationsPerFile: 5
    minRelevanceScore: 0.6
    # Custom capabilities
    capabilities:
      # Optional: enables Programmatic Tool Calling for MCP tools marked Programmatic in the Agent Builder.
      # - 'programmatic_tools'
      - 'execute_code'
      - 'file_search'
      - 'skills'
      - 'subagents'
      - 'actions'
      - 'artifacts'
      - 'context'
      - 'ocr'
      - 'web_search'

Trong ví dụ này:

  • Giao diện trình tạo đã được bật
  • Các trích dẫn tệp bị giới hạn ở mức 20 trích dẫn, với tối đa 5 trích dẫn cho mỗi tệp
  • Chỉ các nguồn có độ liên quan từ 60% trở lên mới được bao gồm
  • Các Agent của LibreChat có quyền truy cập vào thực thi mã, tìm kiếm tệp (có trích dẫn), Skills, Subagents, actions, artifacts, ngữ cảnh tệp, các dịch vụ ocr nếu được cấu hình và khả năng tìm kiếm web.
  • Programmatic Tool Calling vẫn bị vô hiệu hóa trừ khi bạn thêm khả năng programmatic_tools cùng với execute_code

remoteApi

Cấu hình cho xác thực API Remote Agent. Kiểm soát cách các dịch vụ bên ngoài xác thực khi gọi các endpoint của Agents API.

remoteApi.auth

KeyTypeDescriptionExample
authObjectCấu hình xác thực cho Remote Agent API.Supports API key and/or OIDC Bearer token authentication. If omitted, only API key auth is active.

remoteApi.auth.apiKey

KeyTypeDescriptionExample
enabledBooleanBật xác thực khóa API cho Remote Agent API.When true, requests with a valid LibreChat API key are accepted. Can be used alongside or instead of OIDC.

Mặc định: true

remoteApi.auth.oidc

KeyTypeDescriptionExample
enabledBooleanBật xác thực OIDC Bearer token.When true, the middleware validates Bearer tokens against the configured OIDC issuer via JWKS.
issuerStringURL nhà cung cấp OIDC.The base URL of your OIDC provider, such as a Keycloak realm URL. Used for token issuer validation and JWKS discovery if jwksUri is not set.
jwksUriStringURL endpoint JWKS. Tùy chọn.If omitted, resolved automatically via {issuer}/.well-known/openid-configuration. You can also set OPENID_JWKS_URL as an alternative.
audienceStringĐối tượng token dự kiến. Bắt buộc khi OIDC auth được bật.Tokens must contain this value in their aud claim.
scopeStringGiá trị phạm vi bắt buộc. Tùy chọn.If set, the token must contain this value in its scp or scope claim. Use this to distinguish token intent across different APIs.

Mặc định: enabled: false

Ví dụ - Chỉ OIDC:

endpoints:
  agents:
    remoteApi:
      auth:
        apiKey:
          enabled: false
        oidc:
          enabled: true
          issuer: https://auth.example.com/realms/myrealm
          audience: my-client-id

Ví dụ - OIDC với dự phòng API key:

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

Thứ tự ưu tiên phân giải JWKS URI là jwksUri tường minh, sau đó đến OPENID_JWKS_URL, và cuối cùng là tự động khám phá thông qua {issuer}/.well-known/openid-configuration.

Việc khớp người dùng OIDC sử dụng claim sub làm phương thức tra cứu chính, với phương thức dự phòng là các claim email, preferred_username, hoặc upn. Người dùng được khớp phải đã tồn tại trong LibreChat.

Subagents

Trường subagents kiểm soát các tác nhân con biệt lập mà một tác nhân cha có thể tạo ra khi khả năng subagents khả dụng.

KeyTypeDescriptionExample
enabledBooleanThêm công cụ tạo subagent vào agent này khi được đặt là true. Mặc định: bị vô hiệu hóa.enabled: true
allowSelfBooleanCho phép tác nhân tự khởi tạo trong một ngữ cảnh biệt lập mới. Mặc định: true.allowSelf: true
agent_idsArray/List of StringsCác agent cụ thể mà agent này có thể tạo ra. Tối đa: 10.agent_ids: ["agent_researcher"]
subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'

Để biết về hành vi và giới hạn đối với người dùng, hãy xem Subagents.

Ghi chú

  • Không khuyến khích việc vô hiệu hóa giao diện trình tạo (builder interface) trừ khi bạn đang sử dụng modelSpecs để xác định danh sách các tác nhân (agents) để lựa chọn.
  • Cấu hình trích dẫn tệp (maxCitations, maxCitationsPerFile, minRelevanceScore) chỉ áp dụng khi khả năng file_search được bật.
  • Điểm mức độ liên quan được tính toán bằng cách sử dụng độ tương đồng vector, trong đó 1.0 đại diện cho một kết quả khớp hoàn hảo và 0.0 đại diện cho không có sự tương đồng nào.
  • Các giới hạn trích dẫn giúp cân bằng giữa việc truy xuất thông tin toàn diện với chất lượng và hiệu suất phản hồi.
  • Khả năng context hoạt động mà không cần cấu hình OCR bằng cách sử dụng các phương thức phân tích văn bản. OCR giúp nâng cao chất lượng trích xuất khi được cấu hình.
  • Tính năng ocr yêu cầu phải cấu hình một dịch vụ OCR (xem OCR Configuration).

Hướng dẫn này thế nào?

Chỉnh sửa trên GitHub

Cấu trúc đối tượng Assistants endpoint

Trang trước

Cấu trúc đối tượng Actions

Trang tiếp theo

Trên trang này

Ví dụrecursionLimitmaxRecursionLimittitleTimingdisableBuilderallowedProviderscapabilitiesskillsmaxCitationsmaxCitationsPerFileminRelevanceScoreCác ví dụ về cấu hình trích dẫn tệpKhả năng của AgentCấu hình ví dụremoteApiremoteApi.authremoteApi.auth.apiKeyremoteApi.auth.oidcSubagentsGhi chú