diff --git a/content/docs/configuration/librechat_yaml/object_structure/agents.mdx b/content/docs/configuration/librechat_yaml/object_structure/agents.mdx index 426879f74..223ada5fd 100644 --- a/content/docs/configuration/librechat_yaml/object_structure/agents.mdx +++ b/content/docs/configuration/librechat_yaml/object_structure/agents.mdx @@ -19,6 +19,10 @@ endpoints: 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) + remoteApi: + auth: + oidc: + enabled: false ``` > This configuration enables the builder interface for agents. @@ -244,6 +248,79 @@ In this example: - Only sources with 60%+ relevance are included - LibreChat Agents have access to code execution, file search (with citations), actions, artifacts, file context, ocr services if configured, and web search capabilities +## remoteApi + +Configuration for the Remote Agent API authentication. Controls how external services authenticate when calling the Agents API endpoints. + +### remoteApi.auth + + + +#### remoteApi.auth.apiKey + + + +**Default:** `true` + +#### remoteApi.auth.oidc + + + +**Default:** `enabled: false` + +**Example — OIDC only (Keycloak):** +```yaml filename="endpoints / agents / remoteApi" +endpoints: + agents: + remoteApi: + auth: + apiKey: + enabled: false + oidc: + enabled: true + issuer: https://auth.example.com/realms/myrealm + audience: my-client-id +``` + +**Example — OIDC with API key fallback:** +```yaml filename="endpoints / agents / remoteApi" +endpoints: + agents: + remoteApi: + auth: + apiKey: + enabled: true + oidc: + enabled: true + issuer: https://auth.example.com/realms/myrealm + # jwksUri is optional — auto-discovered if omitted + jwksUri: https://auth.example.com/realms/myrealm/protocol/openid-connect/certs +``` + + + JWKS URI resolution priority: explicit `jwksUri` → `OPENID_JWKS_URL` env var → auto-discovery via `{issuer}/.well-known/openid-configuration`. + + + + OIDC user matching uses the `sub` claim as primary lookup, with fallback to `email`, `preferred_username`, or `upn` claims. The matched user must already exist in LibreChat. + + ## Notes - It's not recommended to disable the builder interface unless you are using [modelSpecs](/docs/configuration/librechat_yaml/object_structure/model_specs) to define a list of agents to choose from. diff --git a/content/docs/features/agents_api.mdx b/content/docs/features/agents_api.mdx index e14666f21..4aecd541a 100644 --- a/content/docs/features/agents_api.mdx +++ b/content/docs/features/agents_api.mdx @@ -83,6 +83,53 @@ for chunk in response: print(chunk.choices[0].delta.content, end="") ``` +## Authentication + +The Agents API supports two authentication methods that can be used independently or simultaneously. + +### API Key + +The default authentication method. Generate API keys from the LibreChat UI once `remoteAgents.use` and `remoteAgents.create` are enabled. + +```bash +Authorization: Bearer +``` + +### OIDC Bearer Token + +For machine-to-machine scenarios where your infrastructure already has an OIDC provider (Keycloak, Auth0, Authentik, etc.), you can authenticate directly with OIDC Bearer tokens — no LibreChat API key required. + +Configure in `librechat.yaml`: + +```yaml filename="librechat.yaml" +endpoints: + agents: + remoteApi: + auth: + apiKey: + enabled: false # disable API key auth if OIDC is sufficient + oidc: + enabled: true + issuer: https://auth.example.com/realms/myrealm + # jwksUri is optional — auto-discovered from issuer if omitted + audience: my-client-id +``` + +Then call the API with your OIDC access token: + +```bash +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!"}' +``` + + + The OIDC token must belong to a user that already exists in LibreChat. Matching is done by `sub` claim, with fallback to `email`, `preferred_username`, or `upn`. + + +See [Agents Endpoint — remoteApi](/docs/configuration/librechat_yaml/object_structure/agents#remoteapi) for all configuration options. + ### List Models ```