Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🏛️ feat: Establish Agent Management API Contract (#15545)
Danny Avila04e4fd6b68e7
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex dd414940c1..779f76de33 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -27,6 +27,7 @@ export * from './legacy';export * from './lazySubagents';export * from './lazyHistory';export * from './memory';+export * from './management';export * from './mcpIdentity';export * from './orphans';export * from './migration';diff --git a/packages/api/src/agents/management.spec.ts b/packages/api/src/agents/management.spec.tsnew file mode 100644index 0000000000..68a4232c17--- /dev/null+++ b/packages/api/src/agents/management.spec.ts@@ -0,0 +1,218 @@+import { z } from 'zod';+import { MAX_SUBAGENTS, setMaxSubagents } from 'librechat-data-provider';+import {+ agentManagementCreateSchema,+ agentManagementListResponseSchema,+ agentManagementListSchema,+ agentManagementResponseSchema,+ agentManagementUpdateSchema,+ mapAgentManagementError,+ projectAgentManagementListResponse,+ projectAgentManagementResponse,+} from './management';++const timestamps = {+ createdAt: new Date('2026-09-01T10:00:00.000Z'),+ updatedAt: new Date('2026-09-02T10:00:00.000Z'),+};++const persistedAgent = {+ _id: '64da00000000000000000001',+ id: 'agent_public_id',+ tenantId: 'tenant-secret',+ author: 'user-secret',+ credentials: { apiKey: 'secret' },+ versions: [{}, {}],+ mcpServerNames: ['private-routing-name'],+ is_promoted: true,+ name: 'Researcher',+ description: 'Finds primary sources',+ instructions: 'Be precise',+ provider: 'openAI',+ model: 'gpt-5',+ model_parameters: { temperature: 0.2 },+ tools: ['web_search'],+ skills: ['64da00000000000000000002'],+ conversation_starters: ['Research this'],+ ...timestamps,+};++describe('Agent Management contract', () => {+ describe('inputs', () => {+ it('keeps create and update fields aligned with the browser Agent validators', () => {+ expect(+ agentManagementCreateSchema.parse({+ provider: 'openAI',+ model: 'gpt-5',+ name: 'Researcher',+ stateful_code_environment: 'agent-user',+ subagents: { enabled: true, allowSelf: true, agent_ids: [] },+ }),+ ).toMatchObject({ provider: 'openAI', model: 'gpt-5', tools: [] });++ expect(+ agentManagementUpdateSchema.parse({+ instructions: 'Updated',+ model_parameters: { temperature: 0.1 },+ code_environment_id: null,+ }),+ ).toEqual({+ instructions: 'Updated',+ model_parameters: { temperature: 0.1 },+ code_environment_id: null,+ });+ });++ it.each([agentManagementCreateSchema, agentManagementUpdateSchema])(+ 'rejects unknown and read-only fields',+ (schema) => {+ const base =+ schema === agentManagementCreateSchema ? { provider: 'openAI', model: 'gpt-5' } : {};+ expect(schema.safeParse({ ...base, _id: '64da00000000000000000001' }).success).toBe(false);+ expect(schema.safeParse({ ...base, id: 'agent_forged' }).success).toBe(false);+ expect(schema.safeParse({ ...base, tenantId: 'tenant_forged' }).success).toBe(false);+ expect(schema.safeParse({ ...base, credentials: { apiKey: 'secret' } }).success).toBe(+ false,+ );+ expect(schema.safeParse({ ...base, versions: [] }).success).toBe(false);+ },+ );+ });++ describe('pagination', () => {+ const cursor = Buffer.from(+ JSON.stringify({+ updatedAt: '2026-09-02T10:00:00.000Z',+ _id: '64da00000000000000000001',+ }),+ ).toString('base64');++ it('normalizes a bounded limit and accepts the opaque database cursor', () => {+ expect(agentManagementListSchema.parse({ limit: '25', cursor })).toEqual({+ limit: 25,+ cursor,+ });+ expect(agentManagementListSchema.parse({})).toEqual({ limit: 20 });+ });++ it.each([+ { limit: 0 },+ { limit: 101 },+ { limit: 1.5 },+ { cursor: 'not-a-cursor' },+ {+ cursor: Buffer.from(JSON.stringify({ updatedAt: 'nope', _id: 'nope' })).toString('base64'),+ },+ { search: 'unsupported' },+ ])('rejects invalid list input %#', (input) => {+ expect(agentManagementListSchema.safeParse(input).success).toBe(false);+ });++ it('projects every list item and emits only a usable next cursor', () => {+ const response = projectAgentManagementListResponse({+ data: [persistedAgent],+ has_more: true,+ after: cursor,+ });++ expect(agentManagementListResponseSchema.parse(response)).toEqual(response);+ expect(response).toMatchObject({+ object: 'list',+ first_id: 'agent_public_id',+ last_id: 'agent_public_id',+ has_more: true,+ after: cursor,+ });+ expect(+ projectAgentManagementListResponse({ data: [], has_more: false, after: cursor }),+ ).toEqual({+ object: 'list',+ data: [],+ first_id: null,+ last_id: null,+ has_more: false,+ after: null,+ });++ expect(+ agentManagementListResponseSchema.safeParse({+ ...response,+ has_more: true,+ after: null,+ }).success,+ ).toBe(false);+ });+ });++ describe('responses', () => {+ it('allowlists supported configuration and stable metadata', () => {+ const response = projectAgentManagementResponse(persistedAgent);++ expect(agentManagementResponseSchema.parse(response)).toEqual(response);+ expect(response).toMatchObject({+ id: 'agent_public_id',+ version: 2,+ createdAt: '2026-09-01T10:00:00.000Z',+ updatedAt: '2026-09-02T10:00:00.000Z',+ name: 'Researcher',+ provider: 'openAI',+ model: 'gpt-5',+ });+ expect(response).not.toHaveProperty('_id');+ expect(response).not.toHaveProperty('tenantId');+ expect(response).not.toHaveProperty('author');+ expect(response).not.toHaveProperty('credentials');+ expect(response).not.toHaveProperty('versions');+ expect(response).not.toHaveProperty('mcpServerNames');+ expect(response).not.toHaveProperty('is_promoted');+ });++ it('does not apply the current request admission limit to persisted subagents', () => {+ const subagents = {+ enabled: true,+ agent_ids: Array.from({ length: MAX_SUBAGENTS }, (_, index) => `agent_${index}`),+ };++ setMaxSubagents(1);+ try {+ expect(agentManagementUpdateSchema.safeParse({ subagents }).success).toBe(false);+ expect(projectAgentManagementResponse({ ...persistedAgent, subagents }).subagents).toEqual(+ subagents,+ );+ } finally {+ setMaxSubagents(undefined);+ }+ });+ });++ describe('errors', () => {+ it.each([+ ['not_found', 404, 'Agent not found'],+ ['permission_denied', 403, 'Permission denied'],+ ['internal_error', 500, 'Internal server error'],+ ] as const)('maps %s without leaking an internal error', (code, status, message) => {+ expect(mapAgentManagementError(code, new Error('database password leaked'))).toEqual({+ status,+ body: { error: { code, message } },+ });+ });++ it('maps validation issues to safe paths and messages', () => {+ const validation = z.object({ limit: z.number().max(100) }).safeParse({ limit: 101 });+ if (validation.success) {+ throw new Error('Expected validation to fail');+ }++ expect(mapAgentManagementError('invalid_request', validation.error)).toMatchObject({+ status: 400,+ body: {+ error: {+ code: 'invalid_request',+ message: 'Invalid request',+ details: [{ path: ['limit'] }],+ },+ },+ });+ });+ });+});diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.tsnew file mode 100644index 0000000000..1985fcd1d0--- /dev/null+++ b/packages/api/src/agents/management.ts@@ -0,0 +1,300 @@+import { z } from 'zod';+import type {+ AgentSubagentGraph,+ AgentSubagentGraphEdge,+ AgentSubagentsConfig,+} from 'librechat-data-provider';+import { agentCreateSchema, agentUpdateSchema } from './validation';++const MAX_LIST_LIMIT = 100;+const DEFAULT_LIST_LIMIT = 20;+const MAX_CURSOR_LENGTH = 512;++export type AgentManagementCreate = z.output<typeof agentCreateSchema>;+export type AgentManagementUpdate = z.output<typeof agentUpdateSchema>;+export type AgentManagementList = {+ limit: number;+ cursor?: string;+};+export type AgentManagementResponse = Omit<+ z.output<typeof agentUpdateSchema>,+ 'provider' | 'model'+> & {+ id: string;+ provider: string;+ model: string | null;+ version: number;+ createdAt: string;+ updatedAt: string;+};+export type AgentManagementProjectionSource = Partial<+ Omit<AgentManagementResponse, 'id' | 'provider' | 'model' | 'version' | 'createdAt' | 'updatedAt'>+> & {+ id?: string;+ provider?: string;+ model?: string | null;+ version?: number;+ versions?: readonly object[];+ createdAt?: string | Date;+ updatedAt?: string | Date;+};+export type AgentManagementListProjectionSource = {+ data?: AgentManagementProjectionSource[];+ has_more?: boolean;+ after?: string | null;+};+export type AgentManagementListResponse = {+ object: 'list';+ data: AgentManagementResponse[];+ first_id: string | null;+ last_id: string | null;+ has_more: boolean;+ after: string | null;+};+export type AgentManagementErrorCode =+ | 'invalid_request'+ | 'not_found'+ | 'permission_denied'+ | 'internal_error';+export type AgentManagementError = {+ error: {+ code: AgentManagementErrorCode;+ message: string;+ details?: Array<{ path: Array<string | number>; message: string }>;+ };+};++/**+ * Agent Management accepts the browser-supported configuration fields, but unlike the+ * browser endpoints it rejects unknown top-level fields instead of silently stripping them.+ */+export const agentManagementCreateSchema: z.ZodType<+ AgentManagementCreate,+ z.ZodTypeDef,+ z.input<typeof agentCreateSchema>+> = agentCreateSchema.strict();+export const agentManagementUpdateSchema: z.ZodType<AgentManagementUpdate> =+ agentUpdateSchema.strict();++const agentManagementCursorSchema = z+ .string()+ .min(1)+ .max(MAX_CURSOR_LENGTH)+ .superRefine((cursor, context) => {+ try {+ const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString('utf8')) as unknown;+ const result = z+ .object({+ updatedAt: z.string().datetime(),+ _id: z.string().regex(/^[a-f\d]{24}$/i),+ })+ .strict()+ .safeParse(decoded);++ if (!result.success) {+ context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid cursor' });+ }+ } catch {+ context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid cursor' });+ }+ });++export const agentManagementListSchema: z.ZodType<AgentManagementList, z.ZodTypeDef, unknown> = z+ .object({+ limit: z.coerce.number().int().min(1).max(MAX_LIST_LIMIT).default(DEFAULT_LIST_LIMIT),+ cursor: agentManagementCursorSchema.optional(),+ })+ .strict();++const timestampSchema = z.string().datetime();+const agentManagementGraphEdgeResponseSchema: z.ZodType<AgentSubagentGraphEdge> = z+ .object({+ from: z.union([z.string(), z.array(z.string())]),+ to: z.union([z.string(), z.array(z.string())]),+ description: z.string().optional(),+ edgeType: z.literal('direct'),+ prompt: z.string().optional(),+ excludeResults: z.boolean().optional(),+ })+ .strict();+const agentManagementGraphResponseSchema: z.ZodType<AgentSubagentGraph> = z+ .object({+ type: z.string(),+ name: z.string(),+ description: z.string(),+ agent_ids: z.array(z.string()),+ edges: z.array(agentManagementGraphEdgeResponseSchema),+ entry_agent_id: z.string(),+ result_agent_id: z.string(),+ })+ .strict();+const agentManagementSubagentsResponseSchema: z.ZodType<AgentSubagentsConfig | undefined> = z+ .object({+ enabled: z.boolean().optional(),+ allowSelf: z.boolean().optional(),+ agent_ids: z.array(z.string()).optional(),+ graphs: z.array(agentManagementGraphResponseSchema).optional(),+ })+ .strict()+ .optional();++/** The externally supported Agent shape. Persistence and ownership fields are intentionally absent. */+export const agentManagementResponseSchema: z.ZodType<AgentManagementResponse> = agentUpdateSchema+ .extend({+ id: z.string().min(1),+ provider: z.string(),+ model: z.string().nullable(),+ version: z.number().int().nonnegative(),+ createdAt: timestampSchema,+ updatedAt: timestampSchema,+ subagents: agentManagementSubagentsResponseSchema,+ })+ .strict();++export const agentManagementListResponseSchema: z.ZodType<AgentManagementListResponse> = z+ .object({+ object: z.literal('list'),+ data: z.array(agentManagementResponseSchema),+ first_id: z.string().nullable(),+ last_id: z.string().nullable(),+ has_more: z.boolean(),+ after: agentManagementCursorSchema.nullable(),+ })+ .strict()+ .superRefine(({ has_more, after }, context) => {+ if (has_more !== (after != null)) {+ context.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['after'],+ message: 'A next cursor is required exactly when more results are available',+ });+ }+ });++export const agentManagementErrorCodeSchema: z.ZodType<AgentManagementErrorCode> = z.enum([+ 'invalid_request',+ 'not_found',+ 'permission_denied',+ 'internal_error',+]);++const agentManagementValidationIssueSchema = z+ .object({+ path: z.array(z.union([z.string(), z.number()])),+ message: z.string(),+ })+ .strict();++export const agentManagementErrorSchema: z.ZodType<AgentManagementError> = z+ .object({+ error: z+ .object({+ code: agentManagementErrorCodeSchema,+ message: z.string(),+ details: z.array(agentManagementValidationIssueSchema).optional(),+ })+ .strict(),+ })+ .strict();++function toTimestamp(value: string | Date | undefined): string | undefined {+ if (value instanceof Date) {+ return value.toISOString();+ }+ return value;+}++function getVersion(source: AgentManagementProjectionSource): number | undefined {+ if (source.version != null) {+ return source.version;+ }+ return source.versions?.length;+}++/** Build an external response from a persistence result using an explicit allowlist. */+export function projectAgentManagementResponse(+ source: AgentManagementProjectionSource,+): AgentManagementResponse {+ return agentManagementResponseSchema.parse({+ id: source.id,+ provider: source.provider,+ model: source.model,+ version: getVersion(source),+ createdAt: toTimestamp(source.createdAt),+ updatedAt: toTimestamp(source.updatedAt),+ name: source.name,+ description: source.description,+ instructions: source.instructions,+ avatar: source.avatar,+ model_parameters: source.model_parameters,+ tools: source.tools,+ skills: source.skills,+ skills_enabled: source.skills_enabled,+ skill_authoring_enabled: source.skill_authoring_enabled,+ skills_scope: source.skills_scope,+ memory_scope: source.memory_scope,+ agent_ids: source.agent_ids,+ edges: source.edges,+ end_after_tools: source.end_after_tools,+ hide_sequential_outputs: source.hide_sequential_outputs,+ stateful_code_sessions: source.stateful_code_sessions,+ stateful_code_environment: source.stateful_code_environment,+ code_environment_id: source.code_environment_id,+ artifacts: source.artifacts,+ recursion_limit: source.recursion_limit,+ conversation_starters: source.conversation_starters,+ tool_resources: source.tool_resources,+ tool_options: source.tool_options,+ subagents: source.subagents,+ support_contact: source.support_contact,+ category: source.category,+ });+}++export function projectAgentManagementListResponse(+ source: AgentManagementListProjectionSource,+): AgentManagementListResponse {+ const data = (source.data ?? []).map(projectAgentManagementResponse);+ return agentManagementListResponseSchema.parse({+ object: 'list',+ data,+ first_id: data[0]?.id ?? null,+ last_id: data[data.length - 1]?.id ?? null,+ has_more: source.has_more,+ after: source.has_more === true && typeof source.after === 'string' ? source.after : null,+ });+}++const ERROR_STATUS: Record<AgentManagementErrorCode, number> = {+ invalid_request: 400,+ not_found: 404,+ permission_denied: 403,+ internal_error: 500,+};++const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {+ invalid_request: 'Invalid request',+ not_found: 'Agent not found',+ permission_denied: 'Permission denied',+ internal_error: 'Internal server error',+};++/** Map known failure classes to a stable envelope without exposing internal error messages. */+export function mapAgentManagementError(+ code: AgentManagementErrorCode,+ error?: unknown,+): { status: number; body: AgentManagementError } {+ const details =+ code === 'invalid_request' && error instanceof z.ZodError+ ? error.issues.map(({ path, message }) => ({ path, message }))+ : undefined;+ const body = agentManagementErrorSchema.parse({+ error: {+ code,+ message: ERROR_MESSAGE[code],+ ...(details != null ? { details } : {}),+ },+ });++ return { status: ERROR_STATUS[code], body };+}