Skip to content

✨ feat: Read Conversation Metadata Through the Agents API - #18490

Open
dustinhealy wants to merge 2 commits into
devfrom
feat/conversation-metadata-api
Open

dustinhealy wants to merge 2 commits into
devfrom
feat/conversation-metadata-api

Conversation

@dustinhealy

Copy link
Copy Markdown
Collaborator

Summary

The Agents API exposes GET /api/agents/v1/conversations and GET /api/agents/v1/conversations/{id} for the LibreChat account bound to a management OIDC client. Operators enable access per binding with conversationRead: true under endpoints.agents.managementApi.auth.clients.

The list supports archive, agent and exact tag filters. The cursor preserves ordering when timestamps tie and when older conversations have no update timestamp. Both routes use the account and tenant resolved by the existing management authentication flow and return a fixed metadata projection.

Related to #15682

How it works

The Express router wires the existing management OIDC verifier to the read handlers in packages/api. The data-schemas query applies the owner, tenant and conversation visibility predicates before returning its projection. The generated OpenAPI contract describes both reads.

Type of change

  • Feature

Testing

  • Exercised list, filter, page and detail via the running app with a disposable OIDC issuer and MongoDB. The fixture covers tied and missing update timestamps, exact legacy tag labels, archive and agent filters, visibility, and the not-found response.
  • Ran the existing browser bookmark scenarios, the management middleware suite, the OpenAPI generation and router checks, and type checks in the affected TypeScript workspaces. The serial database latency Lighthouse check passed against the candidate.

Screenshots / recordings

No user interface change.

Risk / compatibility

Existing client bindings require explicit opt-in. The new reads use existing indexes and keep the result page at 100 rows or fewer. On a synthetic fixture with 5,000 conversations for the bound account, the first and deep 20-row pages examined 22 and 23 documents. A sparse or absent tag filter used an owner-bounded index and examined 9,000 document entries, including repeated fetches across visibility branches. The median was 3.3 ms across ten warm local samples. No production latency measurement was taken.

Checklist

  • I reviewed my own changes
  • Relevant tests have been added or updated
  • Existing relevant tests pass
  • The change does not introduce new warnings or errors
  • User-facing or complex behavior is documented where necessary
  • Required dependency changes have been merged/published
  • Required documentation PR — N/A, setup is documented with the API contract

Copilot AI balanced review requested due to automatic review settings November 19, 2026 04:28

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The label-length cap rejects filters for valid stored labels longer than 256 characters, causing HTTP 400 when filtering by labels returned in conversation metadata.

1 open issue
What changed in this PR

Adds read-only conversation metadata endpoints to the Agents API, providing a focused part of the broader conversation-management work in #15682. Access requires explicit opt-in on an OIDC client binding and uses the bound account’s owner and tenant scope.

Changes:

  • Adds list and detail reads with archive, agent, and exact-tag filters.
  • Implements cursor pagination for tied and missing timestamps, with shared conversation visibility rules.
  • Adds access checks, API documentation, and authentication and end-to-end tests.
File Description
packages/​data-schemas/​src/​methods/​index.ts Registers metadata database methods.
packages/​data-schemas/​src/​methods/​conversationMetadata.ts Implements scoped queries, projection, and pagination.
packages/​data-schemas/​src/​index.ts Exports metadata types.
packages/​data-provider/​src/​config.ts Adds the conversationRead binding option.
packages/​api/​src/​openapi/​registry.ts Registers conversation schemas and endpoints.
packages/​api/​src/​openapi/​document.ts Updates the API description to include conversations.
packages/​api/​src/​openapi/​conversations.ts Defines list and detail API contracts.
packages/​api/​src/​middleware/​management.ts Enforces explicit conversation-read access.
packages/​api/​src/​middleware/​management.spec.ts Tests opt-in admission and principal resolution.
packages/​api/​src/​conversations/​metadata.ts Adds validation, cursors, and HTTP handlers.
packages/​api/​src/​conversations/​index.ts Exports metadata handlers and schemas.
packages/​api/​openapi/​agents.openapi.json Publishes generated conversation contracts.
e2e/​specs/​mock/​conversation-metadata.spec.ts Tests filtering, pagination, visibility, and detail reads.
e2e/​setup/​agent-management.ts Enables conversation reads for the test binding.
docs/​conversation-metadata-api.md Documents configuration and endpoint behavior.
api/​server/​routes/​agents/​middleware.js Wires conversation-read authentication.
api/​server/​routes/​agents/​index.js Mounts the conversation router.
api/​server/​routes/​agents/​conversations.js Connects authentication, middleware, and read handlers.

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants