mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-16 21:08:17 +00:00
* 🔗 feat(agents): use LibreChat prompt groups as agent instructions
Agents can link a prompt group revision or Production as their instructions. The link resolves at the start of each turn through a cached resolver. The cache clears on promote and delete. Editors without VIEW on the group see a restricted placeholder.
* fix: remove duplicate logger import from agent initialization tests
* fix: honor prompt management capabilities for linked agent instructions
* test: seed prompt manager capabilities in authorization fixtures
* fix: clear acknowledged linked prompt edits before version restore
* test: adapt merged chain coverage to prompt-aware payload helper
---------
Co-authored-by: Lia <lia@librechat.ai>
269 lines
8.3 KiB
TypeScript
269 lines
8.3 KiB
TypeScript
import { z } from 'zod';
|
|
import type { ZodTypeAny } from 'zod';
|
|
import type { EndpointContract } from './adapter';
|
|
import {
|
|
agentManagementCreateSchema,
|
|
agentManagementUpdateSchema,
|
|
agentManagementListSchema,
|
|
agentManagementResponseSchema,
|
|
agentManagementListEnvelopeSchema,
|
|
agentManagementDeleteResponseSchema,
|
|
agentManagementErrorSchema,
|
|
} from '../agents/management';
|
|
import {
|
|
errorMessageResponseSchema,
|
|
accountDeletionResponseSchema,
|
|
genericServerErrorContent,
|
|
messageResponseSchema,
|
|
jsonParseErrorSchema,
|
|
} from './errors';
|
|
|
|
const TAG = 'Agents';
|
|
const SECURITY = ['oidcBearer'];
|
|
|
|
/**
|
|
* `edges[].prompt` accepts a string or a function at runtime (see agents/validation.ts).
|
|
* OpenAPI cannot express a function, so the document uses a string-only variant of the edge.
|
|
* This changes the document only. The runtime schema is untouched.
|
|
*/
|
|
const documentedEdgeSchema = 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.enum(['handoff', 'direct']).optional(),
|
|
prompt: z.string().optional(),
|
|
excludeResults: z.boolean().optional(),
|
|
promptKey: z.string().optional(),
|
|
});
|
|
|
|
/**
|
|
* Replace only the `edges` field for the document. The schemas are `ZodObject` at runtime
|
|
* (built with `.extend(...).strict()`), but their exported type is the wider `ZodType`, so
|
|
* one cast is needed to reach `.extend`.
|
|
*/
|
|
function withDocumentedEdges(schema: ZodTypeAny): ZodTypeAny {
|
|
return (schema as unknown as z.AnyZodObject).extend({
|
|
edges: z.array(documentedEdgeSchema).optional(),
|
|
});
|
|
}
|
|
|
|
/**
|
|
* `instructionsPrompt` (the Builder's link to a native prompt group) is Builder-only: the
|
|
* Management API's create/update/response schemas omit it entirely (see
|
|
* `packages/api/src/agents/management.ts`), so this document never carries the field —
|
|
* neither the full link shape a request could send nor the restricted stub a Builder
|
|
* response can carry (`packages/api/src/agents/instructions/access.ts`).
|
|
*/
|
|
const agentCreateRequestSchema = withDocumentedEdges(agentManagementCreateSchema);
|
|
const agentUpdateRequestSchema = withDocumentedEdges(agentManagementUpdateSchema);
|
|
const agentResponseSchema = withDocumentedEdges(agentManagementResponseSchema);
|
|
|
|
/**
|
|
* Reuse the enforced list envelope; override only `data` with the documented-edge agent.
|
|
* The envelope is exported as `ZodType`, so reach `.extend` the same way `withDocumentedEdges` does.
|
|
*/
|
|
const agentListResponseSchema = (
|
|
agentManagementListEnvelopeSchema as unknown as z.AnyZodObject
|
|
).extend({
|
|
data: z.array(agentResponseSchema),
|
|
});
|
|
|
|
/** The file endpoints are not validated with Zod at runtime; these schemas describe their hand-built responses. */
|
|
const agentFileSchema = z.object({
|
|
id: z.string(),
|
|
object: z.literal('agent.file'),
|
|
filename: z.string(),
|
|
bytes: z.number().int().nonnegative(),
|
|
mime_type: z.string(),
|
|
purposes: z.array(z.string()),
|
|
created_at: z.string().datetime().nullable(),
|
|
});
|
|
const agentFileListSchema = z.object({
|
|
object: z.literal('list'),
|
|
data: z.array(agentFileSchema),
|
|
});
|
|
const agentFileDeletedSchema = z.object({
|
|
id: z.string(),
|
|
deleted: z.literal(true),
|
|
});
|
|
export const agentComponentSchemas: Record<string, ZodTypeAny> = {
|
|
AgentCreateRequest: agentCreateRequestSchema,
|
|
AgentUpdateRequest: agentUpdateRequestSchema,
|
|
Agent: agentResponseSchema,
|
|
AgentList: agentListResponseSchema,
|
|
AgentDeleted: agentManagementDeleteResponseSchema,
|
|
AgentFile: agentFileSchema,
|
|
AgentFileList: agentFileListSchema,
|
|
AgentFileDeleted: agentFileDeletedSchema,
|
|
Error: agentManagementErrorSchema,
|
|
};
|
|
|
|
const errorResponses = [
|
|
{
|
|
status: 400,
|
|
description: 'Invalid request, or a malformed JSON body',
|
|
schema: z.union([agentManagementErrorSchema, jsonParseErrorSchema]),
|
|
},
|
|
{ status: 401, description: 'Authentication failed', schema: errorMessageResponseSchema },
|
|
{
|
|
status: 403,
|
|
description: 'Permission denied, the caller is banned, or the request fails tenant isolation',
|
|
schema: z.union([
|
|
agentManagementErrorSchema,
|
|
messageResponseSchema,
|
|
errorMessageResponseSchema,
|
|
]),
|
|
},
|
|
{ status: 404, description: 'Not found', schema: agentManagementErrorSchema },
|
|
{
|
|
status: 409,
|
|
description: 'The bound account is being deleted',
|
|
schema: accountDeletionResponseSchema,
|
|
},
|
|
{
|
|
status: 500,
|
|
description:
|
|
'Internal server error. Errors normalized by the route use JSON; the final application error controller sends a text body with the text/html media type.',
|
|
schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]),
|
|
additionalContent: genericServerErrorContent,
|
|
},
|
|
];
|
|
|
|
export const agentContracts: EndpointContract[] = [
|
|
{
|
|
operationId: 'createAgent',
|
|
method: 'post',
|
|
path: '/agents',
|
|
tags: [TAG],
|
|
summary: 'Create an agent',
|
|
security: SECURITY,
|
|
body: agentCreateRequestSchema,
|
|
responses: [
|
|
{ status: 201, description: 'The created agent', schema: agentResponseSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'listAgents',
|
|
method: 'get',
|
|
path: '/agents',
|
|
tags: [TAG],
|
|
summary: 'List agents',
|
|
security: SECURITY,
|
|
query: agentManagementListSchema,
|
|
responses: [
|
|
{ status: 200, description: 'A page of agents', schema: agentListResponseSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'getAgent',
|
|
method: 'get',
|
|
path: '/agents/{id}',
|
|
tags: [TAG],
|
|
summary: 'Get an agent',
|
|
security: SECURITY,
|
|
pathParams: [{ name: 'id', description: 'The agent id' }],
|
|
responses: [
|
|
{ status: 200, description: 'The agent', schema: agentResponseSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'updateAgent',
|
|
method: 'patch',
|
|
path: '/agents/{id}',
|
|
tags: [TAG],
|
|
summary: 'Update an agent',
|
|
security: SECURITY,
|
|
pathParams: [{ name: 'id', description: 'The agent id' }],
|
|
body: agentUpdateRequestSchema,
|
|
responses: [
|
|
{ status: 200, description: 'The updated agent', schema: agentResponseSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'deleteAgent',
|
|
method: 'delete',
|
|
path: '/agents/{id}',
|
|
tags: [TAG],
|
|
summary: 'Delete an agent',
|
|
security: SECURITY,
|
|
pathParams: [{ name: 'id', description: 'The agent id' }],
|
|
responses: [
|
|
{
|
|
status: 200,
|
|
description: 'The agent was deleted',
|
|
schema: agentManagementDeleteResponseSchema,
|
|
},
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'uploadAgentFile',
|
|
method: 'post',
|
|
path: '/agents/{id}/files',
|
|
tags: [TAG],
|
|
summary: 'Upload a file to an agent',
|
|
security: SECURITY,
|
|
pathParams: [{ name: 'id', description: 'The agent id' }],
|
|
rawBody: {
|
|
required: true,
|
|
content: {
|
|
'multipart/form-data': {
|
|
schema: {
|
|
type: 'object',
|
|
required: ['file', 'purpose'],
|
|
properties: {
|
|
file: { type: 'string', format: 'binary' },
|
|
purpose: {
|
|
type: 'string',
|
|
enum: ['file_search', 'execute_code', 'context'],
|
|
description: 'The tool resource the file is uploaded for.',
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
},
|
|
responses: [
|
|
{ status: 200, description: 'The uploaded file', schema: agentFileSchema },
|
|
...errorResponses,
|
|
{
|
|
status: 429,
|
|
description: 'Too many upload requests',
|
|
schema: agentManagementErrorSchema,
|
|
},
|
|
],
|
|
},
|
|
{
|
|
operationId: 'listAgentFiles',
|
|
method: 'get',
|
|
path: '/agents/{id}/files',
|
|
tags: [TAG],
|
|
summary: "List an agent's files",
|
|
security: SECURITY,
|
|
pathParams: [{ name: 'id', description: 'The agent id' }],
|
|
responses: [
|
|
{ status: 200, description: "The agent's files", schema: agentFileListSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
{
|
|
operationId: 'deleteAgentFile',
|
|
method: 'delete',
|
|
path: '/agents/{id}/files/{fileId}',
|
|
tags: [TAG],
|
|
summary: "Delete an agent's file",
|
|
security: SECURITY,
|
|
pathParams: [
|
|
{ name: 'id', description: 'The agent id' },
|
|
{ name: 'fileId', description: 'The file id' },
|
|
],
|
|
responses: [
|
|
{ status: 200, description: 'The file was deleted', schema: agentFileDeletedSchema },
|
|
...errorResponses,
|
|
],
|
|
},
|
|
];
|