Agents 엔드포인트 객체 구조

이 페이지는 agents endpoint에 적용됩니다.

예시

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

이 구성은 에이전트를 위한 빌더 인터페이스를 활성화합니다.

recursionLimit

Key	Type	Description	Example
recursionLimit	Number	에이전트가 실행 중에 취할 수 있는 기본 단계 수를 설정합니다.	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.

기본값: 25

예시:

recursionLimit: 50

에이전트 단계에 대한 자세한 내용은 Max Agent Steps를 참조하세요.

maxRecursionLimit

Key	Type	Description	Example
maxRecursionLimit	Number	에이전트가 실행 중에 취할 수 있는 절대적인 최대 단계 수를 설정합니다.	Defines the upper limit for the recursionLimit that can be set from the UI. This prevents users from setting excessively high values.

기본값: 생략할 경우, recursionLimit의 값으로 설정되거나 recursionLimit 또한 생략된 경우 50으로 설정됩니다.

예시:

maxRecursionLimit: 100

에이전트 단계에 대한 자세한 내용은 Max Agent Steps를 참조하세요.

titleTiming

Key	Type	Description	Example
titleTiming	String	agents endpoint에 대한 대화 제목이 생성되는 시점을 제어합니다. 유효한 값: "immediate" 또는 "final".	Defaults to "immediate".

기본값: "immediate"

사용 가능한 값:

"immediate": 사용자의 첫 번째 메시지를 사용하여 모델 응답과 병렬로 요청이 시작되자마자 제목을 생성합니다.
"final": 전체 응답이 완료될 때까지 제목 생성을 지연합니다. 이는 기존의 레거시 동작을 유지합니다.

예시:

titleTiming: immediate

disableBuilder

Key	Type	Description	Example
disableBuilder	Boolean	에이전트용 빌더 인터페이스의 표시 여부와 사용을 제어합니다.	When set to `true`, disables the builder interface for the agent, limiting direct manual interaction.

기본값: false

예시:

disableBuilder: false

allowedProviders

Key	Type	Description	Example
allowedProviders	Array/List of Strings	Agents 기능에서 사용이 허용된 endpoint 제공자(예: "openAI", "anthropic", "google") 목록을 지정합니다.	If defined, only agents configured with these providers can be initialized. If omitted or empty, all configured providers are allowed.

기본값: [] (빈 목록, 모든 제공자 허용)

참고: 다음 중 하나여야 하며, configuration에 정의된 사용자 지정 endpoint 이름일 수도 있습니다: - openAI, azureOpenAI, google, anthropic, assistants, azureAssistants, bedrock

예시:

allowedProviders:
  - openAI
  - google

capabilities

Key	Type	Description	Example
capabilities	Array/List of Strings	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.

기본값: ["deferred_tools", "execute_code", "file_search", "web_search", "artifacts", "subagents", "actions", "context", "skills", "tools", "chain", "ocr"]

Programmatic Tool Calling은 옵트인(opt-in) 방식입니다. Code Interpreter 배포에 Tool Call Server 구성 요소가 포함된 경우에만 execute_code와 함께 programmatic_tools를 추가하세요.

예시:

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'

참고: 이 필드는 선택 사항입니다. 생략할 경우, 기본 동작은 기본값에 나열된 모든 기능을 포함하는 것입니다.

skills

에이전트에 대한 엔드포인트 수준의 Skills 설정을 제어합니다.

Key	Type	Description	Example
skills.maxCatalogSkills	Number	모델이 볼 수 있는 카탈로그에 노출되는 활성 접근 가능 Skill의 수를 제한합니다. 1에서 100 사이여야 합니다.	maxCatalogSkills: 20

기본값: 런타임 카탈로그 제한을 초과하는 구성된 제한 없음.

예시:

skills:
  maxCatalogSkills: 20

이 설정은 Skills를 비활성화하지 않습니다. Skills의 사용 가능 여부를 제어하려면 skills 기능과 에이전트/Model Specs별 스킬 범위 지정을 사용하세요.

maxCitations

Key	Type	Description	Example
maxCitations	Number	단일 에이전트 응답에 포함될 수 있는 최대 총 인용 횟수를 제어합니다.	When using file_search capability, limits the total number of source citations returned to prevent overwhelming responses while ensuring comprehensive coverage.

기본값: 30

범위: 1-50

예시:

maxCitations: 30

maxCitationsPerFile

Key	Type	Description	Example
maxCitationsPerFile	Number	단일 파일에서 추출할 수 있는 최대 인용 횟수를 제한합니다.	Ensures citation diversity by preventing any single file from dominating the citations, encouraging representation from multiple sources.

기본값: 7

범위: 1-10

예시:

maxCitationsPerFile: 7

minRelevanceScore

Key	Type	Description	Example
minRelevanceScore	Number	응답에 포함될 소스에 대한 최소 관련성 점수 임계값을 설정합니다.	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.

기본값: 0.45 (45% 관련성 임계값)

범위: 0.0-1.0

예시:

minRelevanceScore: 0.45

파일 인용 설정 예시

기본 구성 (균형 잡힘)

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

압도적인 응답을 방지하고 품질이 낮은 일치 항목을 필터링하면서 포괄적인 출처를 제공합니다.

엄격한 구성 (고품질)

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

집중된 응답을 위해 엄격한 제한을 두어 관련성이 매우 높은 인용문만 포함합니다.

포괄적 구성 (연구)

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

관련성 여부와 관계없이 모든 출처를 포함하여, 철저한 연구 작업을 위한 최대 정보 추출.

에이전트 기능 (Agent Capabilities)

capabilities 필드를 사용하면 에이전트에 대한 특정 기능을 활성화하거나 비활성화할 수 있습니다. 사용 가능한 기능은 다음과 같습니다:

deferred_tools: 에이전트가 모든 도구를 사전에 컨텍스트로 로드하는 대신 런타임에 지연된 MCP 도구를 검색할 수 있도록 합니다.
programmatic_tools: 에이전트 빌더(Agent Builder)에서 Programmatic으로 표시된 MCP 도구에 대해 프로그래밍 방식의 도구 호출(Programmatic Tool Calling)을 활성화합니다. execute_code 및 Tool Call Server 구성 요소가 포함된 코드 인터프리터(Code Interpreter) 배포가 필요합니다. 이 기능은 선택 사항이며 기본적으로 활성화되어 있지 않습니다.
execute_code: 에이전트가 코드를 실행할 수 있도록 허용합니다.
file_search: 에이전트가 파일을 검색하고 상호작용할 수 있도록 합니다. 활성화되면 인용 동작은 maxCitations, maxCitationsPerFile 및 minRelevanceScore 설정에 의해 제어됩니다.
web_search: 에이전트가 인터넷을 검색하고 정보를 가져올 수 있도록 웹 검색 기능을 활성화합니다.
artifacts: 에이전트가 대화형 아티팩트(React 컴포넌트, HTML, Mermaid 다이어그램)를 생성할 수 있도록 합니다.
subagents: 격리된 컨텍스트의 하위 에이전트 실행을 활성화합니다. Subagents를 참조하세요.
actions: 에이전트가 미리 정의된 작업을 수행할 수 있도록 허용합니다.
context: 채팅에서 "텍스트로 업로드(Upload as Text)" 기능과 에이전트를 위한 "파일 컨텍스트(File Context)"를 활성화하여, 사용자가 파일을 업로드하고 해당 내용을 추출하여 대화에 직접 포함할 수 있도록 합니다.
skills: 사이드 패널에서 Skills를 활성화하고, 수동 $ 호출, 모델 호출 Skills, 그리고 에이전트 skill 허용 목록을 지원합니다. Skills를 참조하세요.
tools: 에이전트에게 다양한 도구에 대한 액세스 권한을 부여합니다.
chain: 에이전트 체이닝(Mixture-of-Agents (MoA) 워크플로우라고도 함)을 위한 베타 기능을 활성화합니다.
ocr: 채팅에서 "텍스트로 업로드(Upload as Text)" 기능과 에이전트를 위한 "파일 컨텍스트(File Context)"를 선택적으로 향상시켜, 파일을 업로드하고 OCR로 처리할 수 있게 합니다. OCR 서비스를 구성해야 합니다.

기능(capabilities)을 지정하여 사용자가 에이전트와 상호작용할 때 사용할 수 있는 기능을 제어할 수 있습니다.

예시 구성

다음은 사용자 지정 기능 및 파일 인용 설정을 사용하여 agents endpoint를 구성하는 예시입니다:

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'

이 예시에서:

빌더 인터페이스가 활성화되었습니다
파일 인용은 총 20개로 제한되며, 파일당 최대 5개까지 가능합니다.
60% 이상의 관련성을 가진 소스만 포함됩니다
LibreChat 에이전트는 코드 실행, 파일 검색(출처 포함), Skills, Subagents, actions, artifacts, 파일 컨텍스트, 구성된 경우 OCR 서비스, 그리고 웹 검색 기능에 액세스할 수 있습니다.
execute_code와 함께 programmatic_tools 기능을 추가하지 않으면 Programmatic Tool Calling은 비활성화된 상태로 유지됩니다.

remoteApi

Remote Agent API 인증을 위한 설정입니다. 외부 서비스가 Agents API 엔드포인트를 호출할 때 인증하는 방식을 제어합니다.

remoteApi.auth

Key	Type	Description	Example
auth	Object	Remote Agent API를 위한 인증 구성.	Supports API key and/or OIDC Bearer token authentication. If omitted, only API key auth is active.

remoteApi.auth.apiKey

Key	Type	Description	Example
enabled	Boolean	Remote Agent API에 대한 API 키 인증을 활성화합니다.	When true, requests with a valid LibreChat API key are accepted. Can be used alongside or instead of OIDC.

기본값: true

remoteApi.auth.oidc

Key	Type	Description	Example
enabled	Boolean	OIDC Bearer 토큰 인증을 활성화합니다.	When true, the middleware validates Bearer tokens against the configured OIDC issuer via JWKS.
issuer	String	OIDC 발급자 URL.	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.
jwksUri	String	JWKS endpoint URL. 선택 사항입니다.	If omitted, resolved automatically via {issuer}/.well-known/openid-configuration. You can also set OPENID_JWKS_URL as an alternative.
audience	String	예상 토큰 대상(audience)입니다. OIDC 인증이 활성화된 경우 필수입니다.	Tokens must contain this value in their aud claim.
scope	String	필수 범위 값. 선택 사항.	If set, the token must contain this value in its scp or scope claim. Use this to distinguish token intent across different APIs.

기본값: enabled: false

예시 - OIDC 전용:

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

예시 - API 키 폴백을 사용하는 OIDC:

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

JWKS URI 확인 우선순위는 명시적 jwksUri, 그 다음 OPENID_JWKS_URL, 마지막으로 {issuer}/.well-known/openid-configuration을 통한 자동 검색 순입니다.

OIDC 사용자 매칭은 sub 클레임을 기본 조회 값으로 사용하며, email, preferred_username 또는 upn 클레임을 대체 값으로 사용합니다. 매칭되는 사용자는 LibreChat에 이미 존재해야 합니다.

Subagents

subagents 필드는 subagents 기능을 사용할 수 있을 때 부모 에이전트가 생성할 수 있는 격리된 하위 에이전트를 제어합니다.

Key	Type	Description	Example
enabled	Boolean	true일 경우 이 에이전트에 하위 에이전트 생성 도구를 추가합니다. 기본값: 비활성화됨.	enabled: true
allowSelf	Boolean	에이전트가 새롭고 격리된 컨텍스트에서 스스로를 생성할 수 있도록 허용합니다. 기본값: true.	allowSelf: true
agent_ids	Array/List of Strings	이 에이전트가 생성할 수 있는 특정 에이전트입니다. 최대 10개까지 가능합니다.	agent_ids: ["agent_researcher"]

subagents:
  enabled: true
  allowSelf: true
  agent_ids:
    - 'agent_researcher'
    - 'agent_reviewer'

사용자 대상 동작 및 제한 사항은 Subagents를 참조하세요.

참고 사항

modelSpecs를 사용하여 선택할 에이전트 목록을 정의하는 경우가 아니라면, 빌더 인터페이스를 비활성화하는 것은 권장되지 않습니다.
파일 인용 설정(maxCitations, maxCitationsPerFile, minRelevanceScore)은 file_search 기능이 활성화된 경우에만 적용됩니다.
관련성 점수는 벡터 유사도를 사용하여 계산되며, 1.0은 완벽한 일치를, 0.0은 유사성이 없음을 나타냅니다.
인용 제한은 포괄적인 정보 검색과 응답 품질 및 성능 사이의 균형을 맞추는 데 도움을 줍니다.
context 기능은 OCR 설정 없이도 텍스트 파싱 방식을 사용하여 작동합니다. OCR을 설정하면 추출 품질이 향상됩니다.
ocr 기능을 사용하려면 OCR 서비스를 구성해야 합니다 (OCR 구성 참조).