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: OpenAPI spec and docs for the public Agents API (#15928)
Atef Bellaaj69f0dd2a121b
diff --git a/.github/workflows/backend-review.yml b/.github/workflows/backend-review.ymlindex 8416585485..75c8c01ff1 100644--- a/.github/workflows/backend-review.yml+++ b/.github/workflows/backend-review.yml@@ -308,6 +308,9 @@ jobs:- name: Type check @librechat/apirun: npx tsc --noEmit -p packages/api/tsconfig.json+ - name: OpenAPI spec drift check+ run: npm run -w @librechat/api openapi:check+- name: Type check @librechat/clientrun: npx tsc --noEmit -p packages/client/tsconfig.jsondiff --git a/.prettierignore b/.prettierignorenew file mode 100644index 0000000000..fff14af7ac--- /dev/null+++ b/.prettierignore@@ -0,0 +1,3 @@+# Generated artifact. Owned by `npm run -w @librechat/api openapi:generate`,+# checked by `openapi:check`. Do not let Prettier reformat it.+packages/api/openapi/agents.openapi.jsondiff --git a/api/package.json b/api/package.jsonindex 1149d87d39..356b28bd08 100644--- a/api/package.json+++ b/api/package.json@@ -129,6 +129,7 @@"re2js": "^2.8.6","sanitize-html": "^2.17.7","sharp": "^0.35.4",+ "swagger-ui-dist": "^5.32.15","ua-parser-js": "^1.0.36","undici": "^7.29.0","winston": "^3.11.0",diff --git a/api/server/experimental.js b/api/server/experimental.jsindex 61f1842ff3..ef3de373ce 100644--- a/api/server/experimental.js+++ b/api/server/experimental.js@@ -669,6 +669,8 @@ if (cluster.isMaster) {app.use('/api/tags', routes.tags);app.use('/api/mcp', routes.mcp);+ app.use('/api', routes.openapi);+/** 404 for unmatched API routes */app.use('/api', apiNotFound);diff --git a/api/server/index.js b/api/server/index.jsindex b8c0ec5b51..610d5c2c9a 100644--- a/api/server/index.js+++ b/api/server/index.js@@ -448,6 +448,8 @@ const startServer = async () => {app.use('/metrics', metricsRouter);+ app.use('/api', routes.openapi);+/** 404 for unmatched API routes */app.use('/api', apiNotFound);diff --git a/api/server/routes/index.js b/api/server/routes/index.jsindex 7827559f11..14afa6f269 100644--- a/api/server/routes/index.js+++ b/api/server/routes/index.js@@ -25,6 +25,7 @@ const balance = require('./balance');const actions = require('./actions');const apiKeys = require('./apiKeys');const banner = require('./banner');+const openapi = require('./openapi');const search = require('./search');const models = require('./models');const convos = require('./convos');@@ -68,6 +69,7 @@ module.exports = {files,share,banner,+ openapi,agents,convos,traces,diff --git a/api/server/routes/openapi.js b/api/server/routes/openapi.jsnew file mode 100644index 0000000000..fa5f82e0aa--- /dev/null+++ b/api/server/routes/openapi.js@@ -0,0 +1,8 @@+const swaggerUiDist = require('swagger-ui-dist');+const { createOpenApiRouter } = require('@librechat/api');+const { getAppConfig } = require('~/server/services/Config/app');++module.exports = createOpenApiRouter({+ getAppConfig,+ swaggerAssetsPath: swaggerUiDist.getAbsoluteFSPath(),+});diff --git a/e2e/lighthouse/librechat.yaml b/e2e/lighthouse/librechat.yamlindex 494891c355..92ea7d6a4b 100644--- a/e2e/lighthouse/librechat.yaml+++ b/e2e/lighthouse/librechat.yaml@@ -3,3 +3,5 @@ cache: trueendpoints:openAI:titleConvo: false+openapi:+ enabled: truediff --git a/package-lock.json b/package-lock.jsonindex 35f5ed7c84..b3d3619865 100644--- a/package-lock.json+++ b/package-lock.json@@ -147,6 +147,7 @@"re2js": "^2.8.6","sanitize-html": "^2.17.7","sharp": "^0.35.4",+ "swagger-ui-dist": "^5.32.15","ua-parser-js": "^1.0.36","undici": "^7.29.0","winston": "^3.11.0",@@ -16556,6 +16557,13 @@"dev": true,"license": "MIT"},+ "node_modules/@scarf/scarf": {+ "version": "1.4.0",+ "resolved": "https://registry.npmjs.org/@scarf/scarf/-/scarf-1.4.0.tgz",+ "integrity": "sha512-xxeapPiUXdZAE3che6f3xogoJPeZgig6omHEy1rIY5WVsB3H2BHNnZH+gHG6x91SCWyQCzWGsuL2Hh3ClO5/qQ==",+ "hasInstallScript": true,+ "license": "Apache-2.0"+ },"node_modules/@sentry/conventions": {"version": "0.16.0","resolved": "https://registry.npmjs.org/@sentry/conventions/-/conventions-0.16.0.tgz",@@ -39324,6 +39332,15 @@"url": "https://github.com/sponsors/ljharb"}},+ "node_modules/swagger-ui-dist": {+ "version": "5.32.15",+ "resolved": "https://registry.npmjs.org/swagger-ui-dist/-/swagger-ui-dist-5.32.15.tgz",+ "integrity": "sha512-TSFER+rFQlf1nzk6WvKkMaHTxAPQ3eAAxigFThnxQedSREanfZgSbJFayZVs/ULnSbNdrJOb99vLD6xpb3R3eg==",+ "license": "Apache-2.0",+ "dependencies": {+ "@scarf/scarf": "=1.4.0"+ }+ },"node_modules/swr": {"version": "2.3.8","resolved": "https://registry.npmjs.org/swr/-/swr-2.3.8.tgz",@@ -42325,6 +42342,19 @@"url": "https://github.com/sponsors/colinhacks"}},+ "node_modules/zod-openapi": {+ "version": "4.2.4",+ "resolved": "https://registry.npmjs.org/zod-openapi/-/zod-openapi-4.2.4.tgz",+ "integrity": "sha512-tsrQpbpqFCXqVXUzi3TPwFhuMtLN3oNZobOtYnK6/5VkXsNdnIgyNr4r8no4wmYluaxzN3F7iS+8xCW8BmMQ8g==",+ "dev": true,+ "license": "MIT",+ "engines": {+ "node": ">=18"+ },+ "peerDependencies": {+ "zod": "^3.21.4"+ }+ },"node_modules/zod-to-json-schema": {"version": "3.25.1","resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.1.tgz",@@ -42401,7 +42431,8 @@"typescript": "^5.9.3","winston": "^3.17.0","xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",- "yauzl": "^3.2.1"+ "yauzl": "^3.2.1",+ "zod-openapi": "^4.2.4"},"peerDependencies": {"@anthropic-ai/vertex-sdk": "^0.16.0",diff --git a/packages/api/openapi/agents.openapi.json b/packages/api/openapi/agents.openapi.jsonnew file mode 100644index 0000000000..3b1b3efe0d--- /dev/null+++ b/packages/api/openapi/agents.openapi.json@@ -0,0 +1,3802 @@+{+ "openapi": "3.1.0",+ "info": {+ "title": "LibreChat Agents API",+ "version": "0.1.0",+ "description": "The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change."+ },+ "servers": [+ {+ "url": "agents/v1",+ "description": "Relative to where this document is served (`/api/openapi.json`), so it resolves under any deployment base path."+ }+ ],+ "paths": {+ "/agents": {+ "post": {+ "operationId": "createAgent",+ "summary": "Create an agent",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentCreateRequest"+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "The created agent",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Agent"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "get": {+ "operationId": "listAgents",+ "summary": "List agents",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "query",+ "name": "limit",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 20+ }+ },+ {+ "in": "query",+ "name": "cursor",+ "schema": {+ "type": "string",+ "minLength": 1,+ "maxLength": 512+ }+ }+ ],+ "responses": {+ "200": {+ "description": "A page of agents",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentList"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/agents/{id}": {+ "get": {+ "operationId": "getAgent",+ "summary": "Get an agent",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The agent",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Agent"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "patch": {+ "operationId": "updateAgent",+ "summary": "Update an agent",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentUpdateRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "The updated agent",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Agent"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "delete": {+ "operationId": "deleteAgent",+ "summary": "Delete an agent",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The agent was deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentDeleted"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/agents/{id}/files": {+ "post": {+ "operationId": "uploadAgentFile",+ "summary": "Upload a file to an agent",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "requestBody": {+ "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": {+ "200": {+ "description": "The uploaded file",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentFile"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "429": {+ "description": "Too many upload requests",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "get": {+ "operationId": "listAgentFiles",+ "summary": "List an agent's files",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The agent's files",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentFileList"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/agents/{id}/files/{fileId}": {+ "delete": {+ "operationId": "deleteAgentFile",+ "summary": "Delete an agent's file",+ "tags": [+ "Agents"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The agent id",+ "schema": {+ "type": "string"+ },+ "required": true+ },+ {+ "in": "path",+ "name": "fileId",+ "description": "The file id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The file was deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AgentFileDeleted"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/skills": {+ "get": {+ "operationId": "listSkills",+ "summary": "List skills",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "query",+ "name": "limit",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 20+ }+ },+ {+ "in": "query",+ "name": "cursor",+ "schema": {+ "type": "string",+ "minLength": 1,+ "maxLength": 512+ }+ }+ ],+ "responses": {+ "200": {+ "description": "A page of skills",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillList"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/skills/{id}": {+ "get": {+ "operationId": "getSkill",+ "summary": "Get a skill",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The skill id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The skill",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Skill"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "patch": {+ "operationId": "updateSkill",+ "summary": "Update a skill",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The skill id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillUpdateRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "The updated skill",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Skill"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The skill changed since the provided expectedVersion, or the bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ ]+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/skills/{id}/files": {+ "get": {+ "operationId": "listSkillFiles",+ "summary": "List a skill's files",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The skill id",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The skill's files",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillFileList"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ },+ "/skills/{id}/files/{relativePath}": {+ "get": {+ "operationId": "getSkillFile",+ "summary": "Get a skill's file",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The skill id",+ "schema": {+ "type": "string"+ },+ "required": true+ },+ {+ "in": "path",+ "name": "relativePath",+ "description": "The file path within the skill",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "responses": {+ "200": {+ "description": "The file content",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillFileContent"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ },+ "put": {+ "operationId": "updateSkillFile",+ "summary": "Create or update a skill's file",+ "tags": [+ "Skills"+ ],+ "security": [+ {+ "oidcBearer": []+ }+ ],+ "parameters": [+ {+ "in": "path",+ "name": "id",+ "description": "The skill id",+ "schema": {+ "type": "string"+ },+ "required": true+ },+ {+ "in": "path",+ "name": "relativePath",+ "description": "The file path within the skill",+ "schema": {+ "type": "string"+ },+ "required": true+ }+ ],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillFileUpdateRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "The file was written",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/SkillFileUpdated"+ }+ }+ }+ },+ "400": {+ "description": "Invalid request, or a malformed JSON body",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/JsonParseError"+ }+ ]+ }+ }+ }+ },+ "401": {+ "description": "Authentication failed",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ }+ }+ },+ "403": {+ "description": "Permission denied, the caller is banned, or the request fails tenant isolation",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/MessageError"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "409": {+ "description": "The bound account is being deleted",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/AccountDeletionConflict"+ }+ }+ }+ },+ "429": {+ "description": "Too many file-write requests",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/MessageError"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "anyOf": [+ {+ "$ref": "#/components/schemas/Error"+ },+ {+ "$ref": "#/components/schemas/ErrorMessage"+ }+ ]+ }+ }+ }+ }+ }+ }+ }+ },+ "components": {+ "securitySchemes": {+ "oidcBearer": {+ "type": "http",+ "scheme": "bearer",+ "bearerFormat": "JWT",+ "description": "An OIDC access token, sent as a bearer token."+ }+ },+ "schemas": {+ "AgentCreateRequest": {+ "type": "object",+ "properties": {+ "name": {+ "type": [+ "string",+ "null"+ ]+ },+ "description": {+ "type": [+ "string",+ "null"+ ]+ },+ "instructions": {+ "type": [+ "string",+ "null"+ ]+ },+ "avatar": {+ "type": [+ "object",+ "null"+ ],+ "properties": {+ "filepath": {+ "type": "string"+ },+ "source": {+ "type": "string"+ }+ },+ "required": [+ "filepath",+ "source"+ ]+ },+ "model_parameters": {+ "type": "object",+ "additionalProperties": {}+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "default": []+ },+ "skills": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "skills_enabled": {+ "type": "boolean"+ },+ "skill_authoring_enabled": {+ "type": "boolean"+ },+ "skills_scope": {+ "type": "string",+ "enum": [+ "all",+ "selected",+ "none"+ ]+ },+ "memory_scope": {+ "type": "string",+ "enum": [+ "user",+ "agent"+ ]+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "enum": [+ "handoff",+ "direct"+ ]+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ },+ "promptKey": {+ "type": "string"+ }+ },+ "required": [+ "from",+ "to"+ ]+ }+ },+ "end_after_tools": {+ "type": "boolean"+ },+ "hide_sequential_outputs": {+ "type": "boolean"+ },+ "stateful_code_sessions": {+ "type": "boolean"+ },+ "stateful_code_environment": {+ "type": "string",+ "enum": [+ "user",+ "agent-user",+ "conversation"+ ]+ },+ "code_environment_id": {+ "type": "string",+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ },+ "code_workspace_id": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ }+ ]+ },+ "git_identity": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "email": {+ "type": "string",+ "format": "email",+ "maxLength": 254+ }+ },+ "required": [+ "name",+ "email"+ ]+ },+ "artifacts": {+ "type": "string"+ },+ "recursion_limit": {+ "type": "number"+ },+ "conversation_starters": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "tool_resources": {+ "type": "object",+ "properties": {+ "image_edit": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "execute_code": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "file_search": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "vector_store_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "context": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "ocr": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "tool_options": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "defer_loading": {+ "type": "boolean"+ },+ "allowed_callers": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "direct",+ "code_execution"+ ]+ }+ },+ "run_in_background": {+ "type": "boolean"+ },+ "describe_intent": {+ "type": "boolean"+ }+ }+ }+ },+ "subagents": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean"+ },+ "allowSelf": {+ "type": "boolean"+ },+ "shareFiles": {+ "type": "boolean"+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "graphs": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "minLength": 1+ },+ "name": {+ "type": "string",+ "minLength": 1+ },+ "description": {+ "type": "string",+ "minLength": 1+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "maxItems": 32+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "const": "direct"+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ }+ },+ "required": [+ "from",+ "to",+ "edgeType"+ ],+ "additionalProperties": false+ }+ },+ "entry_agent_id": {+ "type": "string"+ },+ "result_agent_id": {+ "type": "string"+ }+ },+ "required": [+ "type",+ "name",+ "description",+ "agent_ids",+ "edges",+ "entry_agent_id",+ "result_agent_id"+ ]+ }+ }+ }+ },+ "support_contact": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "email": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "format": "email"+ }+ ]+ }+ }+ },+ "category": {+ "type": "string"+ },+ "provider": {+ "type": "string"+ },+ "model": {+ "type": "string"+ }+ },+ "required": [+ "provider",+ "model"+ ],+ "additionalProperties": false+ },+ "AgentUpdateRequest": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "instructions": {+ "type": "string"+ },+ "avatar": {+ "type": "null"+ },+ "model_parameters": {+ "type": "object",+ "additionalProperties": {}+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "skills": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "skills_enabled": {+ "type": "boolean"+ },+ "skill_authoring_enabled": {+ "type": "boolean"+ },+ "skills_scope": {+ "type": "string",+ "enum": [+ "all",+ "selected",+ "none"+ ]+ },+ "memory_scope": {+ "type": "string",+ "enum": [+ "user",+ "agent"+ ]+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "enum": [+ "handoff",+ "direct"+ ]+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ },+ "promptKey": {+ "type": "string"+ }+ },+ "required": [+ "from",+ "to"+ ]+ }+ },+ "end_after_tools": {+ "type": "boolean"+ },+ "hide_sequential_outputs": {+ "type": "boolean"+ },+ "stateful_code_sessions": {+ "type": "boolean"+ },+ "stateful_code_environment": {+ "type": "string",+ "enum": [+ "user",+ "agent-user",+ "conversation"+ ]+ },+ "code_environment_id": {+ "type": [+ "string",+ "null"+ ],+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ },+ "code_workspace_id": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ }+ ]+ },+ "git_identity": {+ "type": [+ "object",+ "null"+ ],+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "email": {+ "type": "string",+ "format": "email",+ "maxLength": 254+ }+ },+ "required": [+ "name",+ "email"+ ]+ },+ "artifacts": {+ "type": "string"+ },+ "recursion_limit": {+ "type": "number"+ },+ "conversation_starters": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "tool_resources": {+ "type": "object",+ "properties": {+ "image_edit": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "execute_code": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "file_search": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "vector_store_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "context": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "ocr": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "tool_options": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "defer_loading": {+ "type": "boolean"+ },+ "allowed_callers": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "direct",+ "code_execution"+ ]+ }+ },+ "run_in_background": {+ "type": "boolean"+ },+ "describe_intent": {+ "type": "boolean"+ }+ }+ }+ },+ "subagents": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean"+ },+ "allowSelf": {+ "type": "boolean"+ },+ "shareFiles": {+ "type": "boolean"+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "graphs": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "minLength": 1+ },+ "name": {+ "type": "string",+ "minLength": 1+ },+ "description": {+ "type": "string",+ "minLength": 1+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "maxItems": 32+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "const": "direct"+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ }+ },+ "required": [+ "from",+ "to",+ "edgeType"+ ],+ "additionalProperties": false+ }+ },+ "entry_agent_id": {+ "type": "string"+ },+ "result_agent_id": {+ "type": "string"+ }+ },+ "required": [+ "type",+ "name",+ "description",+ "agent_ids",+ "edges",+ "entry_agent_id",+ "result_agent_id"+ ]+ }+ }+ }+ },+ "support_contact": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "email": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "format": "email"+ }+ ]+ }+ }+ },+ "category": {+ "type": "string"+ },+ "provider": {+ "type": "string"+ },+ "model": {+ "type": "string"+ }+ },+ "additionalProperties": false+ },+ "Agent": {+ "type": "object",+ "properties": {+ "name": {+ "type": [+ "string",+ "null"+ ]+ },+ "description": {+ "type": [+ "string",+ "null"+ ]+ },+ "instructions": {+ "type": [+ "string",+ "null"+ ]+ },+ "avatar": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "filepath": {+ "type": "string"+ },+ "source": {+ "type": "string"+ }+ },+ "required": [+ "filepath",+ "source"+ ]+ },+ {+ "type": "null"+ }+ ]+ },+ "model_parameters": {+ "type": "object",+ "additionalProperties": {}+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "skills": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "skills_enabled": {+ "type": "boolean"+ },+ "skill_authoring_enabled": {+ "type": "boolean"+ },+ "skills_scope": {+ "type": "string",+ "enum": [+ "all",+ "selected",+ "none"+ ]+ },+ "memory_scope": {+ "type": "string",+ "enum": [+ "user",+ "agent"+ ]+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "enum": [+ "handoff",+ "direct"+ ]+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ },+ "promptKey": {+ "type": "string"+ }+ },+ "required": [+ "from",+ "to"+ ]+ }+ },+ "end_after_tools": {+ "type": "boolean"+ },+ "hide_sequential_outputs": {+ "type": "boolean"+ },+ "stateful_code_sessions": {+ "type": "boolean"+ },+ "stateful_code_environment": {+ "type": "string",+ "enum": [+ "user",+ "agent-user",+ "conversation"+ ]+ },+ "code_environment_id": {+ "type": [+ "string",+ "null"+ ],+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ },+ "code_workspace_id": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"+ }+ ]+ },+ "git_identity": {+ "type": [+ "object",+ "null"+ ],+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "email": {+ "type": "string",+ "format": "email",+ "maxLength": 254+ }+ },+ "required": [+ "name",+ "email"+ ]+ },+ "artifacts": {+ "type": "string"+ },+ "recursion_limit": {+ "type": "number"+ },+ "conversation_starters": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "tool_resources": {+ "type": "object",+ "properties": {+ "image_edit": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "execute_code": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "file_search": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "vector_store_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "context": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "ocr": {+ "type": "object",+ "properties": {+ "file_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "tool_options": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "defer_loading": {+ "type": "boolean"+ },+ "allowed_callers": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "direct",+ "code_execution"+ ]+ }+ },+ "run_in_background": {+ "type": "boolean"+ },+ "describe_intent": {+ "type": "boolean"+ }+ }+ }+ },+ "subagents": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "boolean"+ },+ "allowSelf": {+ "type": "boolean"+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "graphs": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string"+ },+ "name": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "agent_ids": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "from": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "to": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ ]+ },+ "description": {+ "type": "string"+ },+ "edgeType": {+ "type": "string",+ "const": "direct"+ },+ "prompt": {+ "type": "string"+ },+ "excludeResults": {+ "type": "boolean"+ }+ },+ "required": [+ "from",+ "to",+ "edgeType"+ ],+ "additionalProperties": false+ }+ },+ "entry_agent_id": {+ "type": "string"+ },+ "result_agent_id": {+ "type": "string"+ }+ },+ "required": [+ "type",+ "name",+ "description",+ "agent_ids",+ "edges",+ "entry_agent_id",+ "result_agent_id"+ ],+ "additionalProperties": false+ }+ }+ },+ "additionalProperties": false+ },+ "support_contact": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "email": {+ "anyOf": [+ {+ "type": "string",+ "const": ""+ },+ {+ "type": "string",+ "format": "email"+ }+ ]+ }+ }+ },+ "category": {+ "type": "string"+ },+ "provider": {+ "type": "string"+ },+ "model": {+ "type": [+ "string",+ "null"+ ]+ },+ "id": {+ "type": "string",+ "minLength": 1+ },+ "version": {+ "type": "integer",+ "minimum": 0+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time"+ }+ },+ "required": [+ "provider",+ "model",+ "id",+ "version",+ "createdAt",+ "updatedAt"+ ],+ "additionalProperties": false+ },+ "AgentList": {+ "type": "object",+ "properties": {+ "object": {+ "type": "string",+ "const": "list"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Agent"+ }+ },+ "first_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "last_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "has_more": {+ "type": "boolean"+ },+ "after": {+ "type": [+ "string",+ "null"+ ],+ "minLength": 1,+ "maxLength": 512+ }+ },+ "required": [+ "object",+ "data",+ "first_id",+ "last_id",+ "has_more",+ "after"+ ],+ "additionalProperties": false+ },+ "AgentDeleted": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "minLength": 1+ },+ "deleted": {+ "type": "boolean",+ "const": true+ }+ },+ "required": [+ "id",+ "deleted"+ ],+ "additionalProperties": false+ },+ "AgentFile": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "object": {+ "type": "string",+ "const": "agent.file"+ },+ "filename": {+ "type": "string"+ },+ "bytes": {+ "type": "integer",+ "minimum": 0+ },+ "mime_type": {+ "type": "string"+ },+ "purposes": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "created_at": {+ "type": [+ "string",+ "null"+ ],+ "format": "date-time"+ }+ },+ "required": [+ "id",+ "object",+ "filename",+ "bytes",+ "mime_type",+ "purposes",+ "created_at"+ ]+ },+ "AgentFileList": {+ "type": "object",+ "properties": {+ "object": {+ "type": "string",+ "const": "list"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/AgentFile"+ }+ }+ },+ "required": [+ "object",+ "data"+ ]+ },+ "AgentFileDeleted": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string"+ },+ "deleted": {+ "type": "boolean",+ "const": true+ }+ },+ "required": [+ "id",+ "deleted"+ ]+ },+ "Error": {+ "type": "object",+ "properties": {+ "error": {+ "type": "object",+ "properties": {+ "code": {+ "type": "string",+ "enum": [+ "invalid_request",+ "not_found",+ "permission_denied",+ "internal_error",+ "conflict"+ ]+ },+ "message": {+ "type": "string"+ },+ "details": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "path": {+ "type": "array",+ "items": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "number"+ }+ ]+ }+ },+ "message": {+ "type": "string"+ }+ },+ "required": [+ "path",+ "message"+ ],+ "additionalProperties": false+ }+ }+ },+ "required": [+ "code",+ "message"+ ],+ "additionalProperties": false+ }+ },+ "required": [+ "error"+ ],+ "additionalProperties": false+ },+ "SkillFrontmatterValue": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "number"+ },+ {+ "type": "boolean"+ },+ {+ "type": "null"+ },+ {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/SkillFrontmatterValue"+ }+ },+ {+ "type": "object",+ "additionalProperties": {+ "$ref": "#/components/schemas/SkillFrontmatterValue"+ }+ }+ ]+ },+ "Skill": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayTitle": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "category": {+ "type": "string"+ },+ "alwaysApply": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "pattern": "^[a-f\\d]{24}$"+ },+ "version": {+ "type": "integer",+ "exclusiveMinimum": 0+ },+ "fileCount": {+ "type": "integer",+ "minimum": 0+ },+ "disableModelInvocation": {+ "type": "boolean"+ },+ "userInvocable": {+ "type": "boolean"+ },+ "allowedTools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time"+ },+ "body": {+ "type": "string"+ },+ "frontmatter": {+ "type": "object",+ "additionalProperties": {+ "$ref": "#/components/schemas/SkillFrontmatterValue"+ }+ }+ },+ "required": [+ "name",+ "description",+ "id",+ "version",+ "fileCount",+ "createdAt",+ "updatedAt",+ "body"+ ]+ },+ "SkillList": {+ "type": "object",+ "properties": {+ "object": {+ "type": "string",+ "const": "list"+ },+ "data": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayTitle": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "category": {+ "type": "string"+ },+ "alwaysApply": {+ "type": "boolean"+ },+ "id": {+ "type": "string",+ "pattern": "^[a-f\\d]{24}$"+ },+ "version": {+ "type": "integer",+ "exclusiveMinimum": 0+ },+ "fileCount": {+ "type": "integer",+ "minimum": 0+ },+ "disableModelInvocation": {+ "type": "boolean"+ },+ "userInvocable": {+ "type": "boolean"+ },+ "allowedTools": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "createdAt": {+ "type": "string",+ "format": "date-time"+ },+ "updatedAt": {+ "type": "string",+ "format": "date-time"+ }+ },+ "required": [+ "name",+ "description",+ "id",+ "version",+ "fileCount",+ "createdAt",+ "updatedAt"+ ]+ }+ },+ "first_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "last_id": {+ "type": [+ "string",+ "null"+ ]+ },+ "has_more": {+ "type": "boolean"+ },+ "after": {+ "type": [+ "string",+ "null"+ ]+ }+ },+ "required": [+ "object",+ "data",+ "first_id",+ "last_id",+ "has_more",+ "after"+ ]+ },+ "SkillUpdateRequest": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string"+ },+ "displayTitle": {+ "type": "string"+ },+ "description": {+ "type": "string"+ },+ "category": {+ "type": "string"+ },+ "alwaysApply": {+ "type": "boolean"+ },+ "body": {+ "type": "string"+ },+ "frontmatter": {+ "type": "object",+ "additionalProperties": {+ "$ref": "#/components/schemas/SkillFrontmatterValue"+ }+ },+ "expectedVersion": {+ "type": "integer",+ "exclusiveMinimum": 0+ }+ },+ "required": [+ "expectedVersion"+ ],+ "additionalProperties": false,+ "minProperties": 2+ },+ "SkillFile": {+ "type": "object",+ "properties": {+ "relativePath": {+ "type": "string"+ },+ "filename": {+ "type": "string"+ },+ "mimeType": {+ "type": "string"+ },+ "bytes": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "relativePath",+ "filename",+ "mimeType",+ "bytes"+ ]+ },+ "SkillFileList": {+ "type": "object",+ "properties": {+ "object": {+ "type": "string",+ "const": "list"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/SkillFile"+ }+ }+ },+ "required": [+ "object",+ "data"+ ]+ },+ "SkillFileContent": {+ "type": "object",+ "properties": {+ "relativePath": {+ "type": "string"+ },+ "filename": {+ "type": "string"+ },+ "mimeType": {+ "type": "string"+ },+ "bytes": {+ "type": "integer",+ "minimum": 0+ },+ "content": {+ "type": "string"+ },+ "isBinary": {+ "type": "boolean"+ }+ },+ "required": [+ "relativePath",+ "filename",+ "mimeType",+ "bytes",+ "isBinary"+ ]+ },+ "SkillFileUpdateRequest": {+ "type": "object",+ "properties": {+ "content": {+ "type": "string",+ "maxLength": 1048576,+ "description": "The file content. The accepted maximum is 1 MiB (1,048,576 bytes) of UTF-8-encoded content. The limit is measured in bytes, not characters, so non-ASCII content reaches it at fewer characters."+ }+ },+ "required": [+ "content"+ ],+ "additionalProperties": false+ },+ "SkillFileUpdated": {+ "type": "object",+ "properties": {+ "relativePath": {+ "type": "string"+ },+ "bytes": {+ "type": "integer",+ "minimum": 0+ }+ },+ "required": [+ "relativePath",+ "bytes"+ ]+ },+ "ErrorMessage": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string"+ }+ },+ "required": [+ "error"+ ],+ "additionalProperties": false+ },+ "AccountDeletionConflict": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string"+ },+ "code": {+ "type": "string",+ "const": "ACCOUNT_DELETION_IN_PROGRESS"+ }+ },+ "required": [+ "error",+ "code"+ ],+ "additionalProperties": false+ },+ "MessageError": {+ "type": "object",+ "properties": {+ "message": {+ "type": "string"+ }+ },+ "required": [+ "message"+ ],+ "additionalProperties": false+ },+ "JsonParseError": {+ "type": "object",+ "properties": {+ "error": {+ "type": "string",+ "const": "Invalid JSON format"+ },+ "message": {+ "type": "string"+ }+ },+ "required": [+ "error",+ "message"+ ],+ "additionalProperties": false+ }+ }+ }+}diff --git a/packages/api/package.json b/packages/api/package.jsonindex 9529ee0ff2..1faf92ab1d 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -27,10 +27,11 @@},"scripts": {"clean": "rimraf dist",- "build": "npm run clean && tsdown",- "build:dev": "npm run clean && tsdown",- "build:watch": "tsdown --watch",- "build:watch:prod": "tsdown --watch",+ "build": "npm run clean && tsdown && npm run openapi:copy",+ "build:dev": "npm run clean && tsdown && npm run openapi:copy",+ "build:watch": "npm run openapi:copy && tsdown --watch",+ "build:watch:prod": "npm run openapi:copy && tsdown --watch",+ "openapi:copy": "node -e \"const fs=require('fs');fs.mkdirSync('dist',{recursive:true});fs.copyFileSync('openapi/agents.openapi.json','dist/agents.openapi.json')\"","test": "jest --coverage --watch --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"","test:ci": "jest --coverage --ci --testPathIgnorePatterns=\"\\.*integration\\.|\\.*helper\\.|__tests__/helpers/|\\.*manual\\.spec\\.\"","test:cache-integration:core": "jest --testPathPatterns=\"src/(cache|middleware)/.*\\.cache_integration\\.(spec|test)\\.ts$\" --coverage=false",@@ -43,8 +44,10 @@"test:agents-integration": "jest --testPathPatterns=\"src/agents/.*\\.integration\\.spec\\.ts$\" --coverage=false --runInBand --forceExit","verify": "npm run test:ci","b:clean": "bun run rimraf dist",- "b:build": "bun run b:clean && bun run tsdown",- "b:build:dev": "bun run b:clean && bun run tsdown",+ "b:build": "bun run b:clean && bun run tsdown && bun run openapi:copy",+ "b:build:dev": "bun run b:clean && bun run tsdown && bun run openapi:copy",+ "openapi:generate": "cross-env TS_NODE_PROJECT=tsconfig.openapi.json ts-node -r tsconfig-paths/register src/openapi/generate.ts --write",+ "openapi:check": "cross-env TS_NODE_PROJECT=tsconfig.openapi.json ts-node -r tsconfig-paths/register src/openapi/generate.ts --check","start:everything-sse": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/examples/everything/sse.ts","start:everything": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/demo/everything.ts","start:filesystem": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/demo/filesystem.ts",@@ -97,7 +100,8 @@"typescript": "^5.9.3","winston": "^3.17.0","xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",- "yauzl": "^3.2.1"+ "yauzl": "^3.2.1",+ "zod-openapi": "^4.2.4"},"publishConfig": {"registry": "https://registry.npmjs.org/"diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.tsindex f45e9bc6d1..1573243b5e 100644--- a/packages/api/src/agents/management.ts+++ b/packages/api/src/agents/management.ts@@ -181,7 +181,8 @@ export const agentManagementResponseSchema: z.ZodType<AgentManagementResponse> =}).strict();-export const agentManagementListResponseSchema: z.ZodType<AgentManagementListResponse> = z+/** The list envelope as a plain object, so the OpenAPI contract can reuse it and override only `data`. */+export const agentManagementListEnvelopeSchema: z.ZodType<AgentManagementListResponse> = z.object({object: z.literal('list'),data: z.array(agentManagementResponseSchema),@@ -190,8 +191,10 @@ export const agentManagementListResponseSchema: z.ZodType<AgentManagementListReshas_more: z.boolean(),after: agentManagementCursorSchema.nullable(),})- .strict()- .superRefine(({ has_more, after }, context) => {+ .strict();++export const agentManagementListResponseSchema: z.ZodType<AgentManagementListResponse> =+ agentManagementListEnvelopeSchema.superRefine(({ has_more, after }, context) => {if (has_more !== (after != null)) {context.addIssue({code: z.ZodIssueCode.custom,diff --git a/packages/api/src/index.ts b/packages/api/src/index.tsindex a1bb4dd789..3e71702fbc 100644--- a/packages/api/src/index.ts+++ b/packages/api/src/index.ts@@ -121,6 +121,9 @@ export * from './stream';export { memoryDiagnostics } from './utils/memory';/* RUM */export * from './rum/proxy';+/* OpenAPI */+export { createOpenApiRouter } from './openapi/router';+export type { OpenApiRouterDeps } from './openapi/router';/* types */export type * from './mcp/types';export type * from './flow/types';diff --git a/packages/api/src/openapi/adapter.ts b/packages/api/src/openapi/adapter.tsnew file mode 100644index 0000000000..846ef8fcb3--- /dev/null+++ b/packages/api/src/openapi/adapter.ts@@ -0,0 +1,165 @@+import { z } from 'zod';+import { createDocument } from 'zod-openapi';+import type { ZodTypeAny } from 'zod';++/**+ * The seam. This is the only file that imports the Zod-to-OpenAPI converter.+ * If we replace the converter, only this file changes.+ */++export type SecurityScheme = {+ type: string;+ scheme?: string;+ bearerFormat?: string;+ description?: string;+};++/** A media-type object written by hand, for requests or responses that have no Zod schema. */+export type RawContent = Record<string, { schema: Record<string, unknown> }>;++export type ResponseContract = {+ status: number;+ description: string /** A Zod schema. When it is also listed in `componentSchemas`, the document uses a `$ref`. */;+ schema?: ZodTypeAny;+ /** A hand-written media-type object, used when there is no Zod schema. */+ content?: RawContent;+};++export type EndpointContract = {+ operationId: string;+ method: 'get' | 'post' | 'patch' | 'delete' | 'put';+ /** OpenAPI-style path, relative to the server base, e.g. `/agents/{id}`. */+ path: string;+ tags: string[];+ summary: string;+ description?: string;+ /** Names of the security schemes that apply to this endpoint. */+ security: string[];+ pathParams?: { name: string; description?: string }[];+ /** An object schema whose fields become query parameters. */+ query?: ZodTypeAny;+ /** A JSON request body. When it is also listed in `componentSchemas`, the document uses a `$ref`. */+ body?: ZodTypeAny;+ /** A hand-written request body, used for multipart uploads. */+ rawBody?: { description?: string; required?: boolean; content: RawContent };+ responses: ResponseContract[];+};++export type OpenApiInput = {+ info: { title: string; version: string; description?: string };+ servers: { url: string; description?: string }[];+ securitySchemes: Record<string, SecurityScheme>;+ /** Named schemas that become reusable `#/components/schemas` entries. */+ componentSchemas: Record<string, ZodTypeAny>;+ /**+ * Extra OpenAPI keywords merged into a generated component schema, keyed by component name.+ * Use this for constraints the converter cannot express, such as an object-level `.refine()`.+ */+ componentSchemaOverrides?: Record<string, Record<string, unknown>>;+ contracts: EndpointContract[];+};++function buildResponses(responses: ResponseContract[]): Record<string, unknown> {+ const result: Record<string, unknown> = {};+ for (const response of responses) {+ if (response.content) {+ result[response.status] = { description: response.description, content: response.content };+ continue;+ }+ if (response.schema) {+ result[response.status] = {+ description: response.description,+ content: { 'application/json': { schema: response.schema } },+ };+ continue;+ }+ result[response.status] = { description: response.description };+ }+ return result;+}++function buildOperation(contract: EndpointContract): Record<string, unknown> {+ const operation: Record<string, unknown> = {+ operationId: contract.operationId,+ summary: contract.summary,+ tags: contract.tags,+ security: contract.security.map((name) => ({ [name]: [] })),+ responses: buildResponses(contract.responses),+ };+ if (contract.description) {+ operation.description = contract.description;+ }+ const requestParams: Record<string, unknown> = {};+ if (contract.pathParams?.length) {+ requestParams.path = z.object(+ Object.fromEntries(+ contract.pathParams.map((param) => [+ param.name,+ param.description ? z.string().describe(param.description) : z.string(),+ ]),+ ),+ );+ }+ if (contract.query) {+ requestParams.query = contract.query;+ }+ if (Object.keys(requestParams).length > 0) {+ operation.requestParams = requestParams;+ }+ if (contract.rawBody) {+ operation.requestBody = {+ description: contract.rawBody.description,+ required: contract.rawBody.required ?? false,+ content: contract.rawBody.content,+ };+ } else if (contract.body) {+ operation.requestBody = {+ required: true,+ content: { 'application/json': { schema: contract.body } },+ };+ }+ return operation;+}++/** Merge extra OpenAPI keywords into generated component schemas the converter built too loosely. */+function applyComponentSchemaOverrides(+ document: Record<string, unknown>,+ overrides?: Record<string, Record<string, unknown>>,+): void {+ if (!overrides) {+ return;+ }+ const components = document.components as+ | { schemas?: Record<string, Record<string, unknown>> }+ | undefined;+ const schemas = components?.schemas;+ if (!schemas) {+ return;+ }+ for (const [name, extra] of Object.entries(overrides)) {+ if (schemas[name]) {+ Object.assign(schemas[name], extra);+ }+ }+}++export function buildOpenApiDocument(input: OpenApiInput): Record<string, unknown> {+ const paths: Record<string, Record<string, unknown>> = {};+ for (const contract of input.contracts) {+ paths[contract.path] ??= {};+ paths[contract.path][contract.method] = buildOperation(contract);+ }+ const spec = {+ openapi: '3.1.0',+ info: input.info,+ servers: input.servers,+ components: {+ securitySchemes: input.securitySchemes,+ schemas: input.componentSchemas,+ },+ paths,+ } as unknown as Parameters<typeof createDocument>[0];+ const document = createDocument(spec) as unknown as Record<string, unknown>;+ applyComponentSchemaOverrides(document, input.componentSchemaOverrides);+ return document;+}diff --git a/packages/api/src/openapi/agents.ts b/packages/api/src/openapi/agents.tsnew file mode 100644index 0000000000..85c77b5c15--- /dev/null+++ b/packages/api/src/openapi/agents.ts@@ -0,0 +1,260 @@+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,+ 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(),+ });+}++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',+ schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]),+ },+];++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,+ ],+ },+];diff --git a/packages/api/src/openapi/document.ts b/packages/api/src/openapi/document.tsnew file mode 100644index 0000000000..e314962e0a--- /dev/null+++ b/packages/api/src/openapi/document.ts@@ -0,0 +1,28 @@+import { securitySchemes, componentSchemas, componentSchemaOverrides, contracts } from './registry';+import { buildOpenApiDocument } from './adapter';++/** Stable document version, independent of the package version, so the artifact does not churn. */+const DOCUMENT_VERSION = '0.1.0';++/** Build the OpenAPI 3.1 document for the public agent and skill management endpoints. */+export function buildAgentsOpenApiDocument(): Record<string, unknown> {+ return buildOpenApiDocument({+ info: {+ title: 'LibreChat Agents API',+ version: DOCUMENT_VERSION,+ description:+ 'The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change.',+ },+ servers: [+ {+ url: 'agents/v1',+ description:+ 'Relative to where this document is served (`/api/openapi.json`), so it resolves under any deployment base path.',+ },+ ],+ securitySchemes,+ componentSchemas,+ componentSchemaOverrides,+ contracts,+ });+}diff --git a/packages/api/src/openapi/errors.ts b/packages/api/src/openapi/errors.tsnew file mode 100644index 0000000000..ce08670741--- /dev/null+++ b/packages/api/src/openapi/errors.ts@@ -0,0 +1,35 @@+import { z } from 'zod';++/**+ * The flat `{ error }` envelope the auth middleware sends for 401 (`{ error: 'Unauthorized' }`)+ * and for its own 500 (`{ error: 'Internal server error' }`). One field, distinct from the nested+ * `agentManagementErrorSchema`.+ */+export const errorMessageResponseSchema: z.ZodType<{ error: string }> = z+ .object({ error: z.string() })+ .strict();++/**+ * When the bound account is being deleted, the auth middleware sends 409 with a flat+ * `{ error, code: 'ACCOUNT_DELETION_IN_PROGRESS' }` body. The code is a fixed discriminator.+ */+export const accountDeletionResponseSchema: z.ZodType<{+ error: string;+ code: 'ACCOUNT_DELETION_IN_PROGRESS';+}> = z.object({ error: z.string(), code: z.literal('ACCOUNT_DELETION_IN_PROGRESS') }).strict();++/**+ * The ban middleware (403) and the default file-upload limiter (429) send a flat `{ message }`+ * body, distinct from the other error shapes.+ */+export const messageResponseSchema: z.ZodType<{ message: string }> = z+ .object({ message: z.string() })+ .strict();++/**+ * The global JSON body parser runs before these routes and, on malformed JSON, returns 400 with+ * a flat `{ error: 'Invalid JSON format', message }` body. The `error` field is a fixed discriminator.+ */+export const jsonParseErrorSchema: z.ZodType<{ error: 'Invalid JSON format'; message: string }> = z+ .object({ error: z.literal('Invalid JSON format'), message: z.string() })+ .strict();diff --git a/packages/api/src/openapi/generate.ts b/packages/api/src/openapi/generate.tsnew file mode 100644index 0000000000..c6f85e3fc6--- /dev/null+++ b/packages/api/src/openapi/generate.ts@@ -0,0 +1,38 @@+import fs from 'fs';+import path from 'path';+import { buildAgentsOpenApiDocument } from './document';++/** Run from the package root (`npm run -w @librechat/api openapi:...`), so cwd is packages/api. */+const SPEC_PATH = path.resolve(process.cwd(), 'openapi', 'agents.openapi.json');++function render(): string {+ return JSON.stringify(buildAgentsOpenApiDocument(), null, 2) + '\n';+}++function write(): void {+ const json = render();+ fs.mkdirSync(path.dirname(SPEC_PATH), { recursive: true });+ fs.writeFileSync(SPEC_PATH, json);+ console.log(`Wrote ${SPEC_PATH}`);+}++function check(): void {+ const json = render();+ const existing = fs.existsSync(SPEC_PATH) ? fs.readFileSync(SPEC_PATH, 'utf8') : '';+ if (existing !== json) {+ console.error(+ 'The committed OpenAPI spec does not match the code. Run: npm run -w @librechat/api openapi:generate',+ );+ process.exit(1);+ }+ console.log('The committed OpenAPI spec matches the code.');+}++if (process.argv.includes('--write')) {+ write();+} else if (process.argv.includes('--check')) {+ check();+} else {+ console.error('Pass --write or --check.');+ process.exit(2);+}diff --git a/packages/api/src/openapi/registry.ts b/packages/api/src/openapi/registry.tsnew file mode 100644index 0000000000..c694aa995c--- /dev/null+++ b/packages/api/src/openapi/registry.ts@@ -0,0 +1,55 @@+import type { ZodTypeAny } from 'zod';+import type { EndpointContract, SecurityScheme } from './adapter';+import {+ errorMessageResponseSchema,+ accountDeletionResponseSchema,+ messageResponseSchema,+ jsonParseErrorSchema,+} from './errors';+import { agentComponentSchemas, agentContracts } from './agents';+import { skillComponentSchemas, skillContracts } from './skills';++/** The agent and skill management endpoints authenticate with an OIDC access token (bearer). */+export const securitySchemes: Record<string, SecurityScheme> = {+ oidcBearer: {+ type: 'http',+ scheme: 'bearer',+ bearerFormat: 'JWT',+ description: 'An OIDC access token, sent as a bearer token.',+ },+};++export const componentSchemas: Record<string, ZodTypeAny> = {+ ...agentComponentSchemas,+ ...skillComponentSchemas,+ ErrorMessage: errorMessageResponseSchema,+ AccountDeletionConflict: accountDeletionResponseSchema,+ MessageError: messageResponseSchema,+ JsonParseError: jsonParseErrorSchema,+};++/**+ * Constraints the Zod-to-OpenAPI converter cannot emit, applied to the generated component.+ * `SkillUpdateRequest`'s object-level `.refine()` (at least one update field) is lost in+ * conversion; `minProperties: 2` keeps `expectedVersion` plus at least one real field.+ *+ * `SkillFileUpdateRequest.content` uses `maxLength`, which counts characters, but `updateFile`+ * (skills/management.ts) rejects when the UTF-8 buffer exceeds 1 MiB. The converter drops the+ * field description, so restate the single `content` property here with the byte limit. The+ * component has only this property, so the whole `properties` object is stated, not clobbered.+ */+export const componentSchemaOverrides: Record<string, Record<string, unknown>> = {+ SkillUpdateRequest: { minProperties: 2 },+ SkillFileUpdateRequest: {+ properties: {+ content: {+ type: 'string',+ maxLength: 1024 * 1024,+ description:+ 'The file content. The accepted maximum is 1 MiB (1,048,576 bytes) of UTF-8-encoded content. The limit is measured in bytes, not characters, so non-ASCII content reaches it at fewer characters.',+ },+ },+ },+};++export const contracts: EndpointContract[] = [...agentContracts, ...skillContracts];diff --git a/packages/api/src/openapi/router.ts b/packages/api/src/openapi/router.tsnew file mode 100644index 0000000000..ce1e6b0ba0--- /dev/null+++ b/packages/api/src/openapi/router.ts@@ -0,0 +1,108 @@+import fs from 'fs';+import path from 'path';+import express from 'express';+import { logger, type AppConfig } from '@librechat/data-schemas';+import type { Request, Response, Router, NextFunction } from 'express';+import type { GetAppConfigOptions } from '~/app/service';++export interface OpenApiRouterDeps {+ /**+ * Resolves the app configuration. The docs gate reads the deployment-wide base config,+ * so `openapi.enabled` comes from `librechat.yaml` and needs no per-request database read.+ */+ getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;+ /** Absolute path to the bundled Swagger UI assets (from `swagger-ui-dist`). */+ swaggerAssetsPath: string;+}++/** The generated spec is copied next to the built bundle, so it ships wherever `dist` ships. */+const SPEC_PATH = path.join(__dirname, 'agents.openapi.json');++/**+ * URLs are computed in the browser from the current path, so the docs work whether LibreChat+ * is served at the origin root or under a base path (e.g. `/chat`) that a proxy strips.+ */+const DOCS_HTML = `<!DOCTYPE html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>LibreChat Agents API</title>+ <script>+ window.addEventListener('DOMContentLoaded', function () {+ var apiBase = location.pathname.replace(/\\/+$/, '').replace(/\\/docs$/, '');+ var link = document.createElement('link');+ link.rel = 'stylesheet';+ link.href = apiBase + '/docs/assets/swagger-ui.css';+ document.head.appendChild(link);+ var script = document.createElement('script');+ script.src = apiBase + '/docs/assets/swagger-ui-bundle.js';+ script.onload = function () {+ window.ui = SwaggerUIBundle({ url: apiBase + '/openapi.json', dom_id: '#swagger-ui' });+ };+ document.body.appendChild(script);+ });+ </script>+ </head>+ <body>+ <div id="swagger-ui"></div>+ </body>+</html>`;++/** Serves the OpenAPI spec and Swagger UI docs behind the `openapi.enabled` config flag. */+export function createOpenApiRouter(deps: OpenApiRouterDeps): Router {+ const router = express.Router();+ let cachedSpec: string | undefined;++ function readSpec(): string {+ if (cachedSpec === undefined) {+ cachedSpec = fs.readFileSync(SPEC_PATH, 'utf8');+ }+ return cachedSpec;+ }++ async function isEnabled(): Promise<boolean> {+ try {+ const appConfig = await deps.getAppConfig({ baseOnly: true });+ return appConfig?.config?.openapi?.enabled === true;+ } catch (error) {+ logger.error('[openapi] Failed to read app config', error);+ return false;+ }+ }++ router.get('/openapi.json', async (_req: Request, res: Response): Promise<void> => {+ if (!(await isEnabled())) {+ res.status(404).json({ message: 'Not Found' });+ return;+ }+ try {+ res.type('application/json').send(readSpec());+ } catch (error) {+ logger.error('[openapi] Failed to read the OpenAPI spec', error);+ res.status(500).json({ message: 'Failed to read the OpenAPI spec' });+ }+ });++ const serveAssets = express.static(deps.swaggerAssetsPath);+ router.use(+ '/docs/assets',+ async (req: Request, res: Response, next: NextFunction): Promise<void> => {+ if (!(await isEnabled())) {+ res.status(404).json({ message: 'Not Found' });+ return;+ }+ serveAssets(req, res, next);+ },+ );++ router.get('/docs', async (_req: Request, res: Response): Promise<void> => {+ if (!(await isEnabled())) {+ res.status(404).json({ message: 'Not Found' });+ return;+ }+ res.type('html').send(DOCS_HTML);+ });++ return router;+}diff --git a/packages/api/src/openapi/skills.ts b/packages/api/src/openapi/skills.tsnew file mode 100644index 0000000000..5e2495c052--- /dev/null+++ b/packages/api/src/openapi/skills.ts@@ -0,0 +1,176 @@+import { z } from 'zod';+import type { ZodTypeAny } from 'zod';+import type { EndpointContract } from './adapter';+import {+ skillManagementUpdateSchema,+ skillManagementResponseSchema,+ skillSummarySchema,+ skillFileSchema,+ skillFileContentSchema,+ skillFileUpdateSchema,+ skillFrontmatterValueSchema,+} from '../skills/management';+import {+ errorMessageResponseSchema,+ accountDeletionResponseSchema,+ messageResponseSchema,+ jsonParseErrorSchema,+} from './errors';+import { agentManagementListSchema, agentManagementErrorSchema } from '../agents/management';++const TAG = 'Skills';+const SECURITY = ['oidcBearer'];++const skillListResponseSchema = z.object({+ object: z.literal('list'),+ data: z.array(skillSummarySchema),+ first_id: z.string().nullable(),+ last_id: z.string().nullable(),+ has_more: z.boolean(),+ after: z.string().nullable(),+});+const skillFileListResponseSchema = z.object({+ object: z.literal('list'),+ data: z.array(skillFileSchema),+});+const skillFileUpdatedSchema = z.object({+ relativePath: z.string(),+ bytes: z.number().int().nonnegative(),+});++export const skillComponentSchemas: Record<string, ZodTypeAny> = {+ SkillFrontmatterValue: skillFrontmatterValueSchema,+ Skill: skillManagementResponseSchema,+ SkillList: skillListResponseSchema,+ SkillUpdateRequest: skillManagementUpdateSchema,+ SkillFile: skillFileSchema,+ SkillFileList: skillFileListResponseSchema,+ SkillFileContent: skillFileContentSchema,+ SkillFileUpdateRequest: skillFileUpdateSchema,+ SkillFileUpdated: skillFileUpdatedSchema,+};++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',+ schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]),+ },+];++export const skillContracts: EndpointContract[] = [+ {+ operationId: 'listSkills',+ method: 'get',+ path: '/skills',+ tags: [TAG],+ summary: 'List skills',+ security: SECURITY,+ query: agentManagementListSchema,+ responses: [+ { status: 200, description: 'A page of skills', schema: skillListResponseSchema },+ ...errorResponses,+ ],+ },+ {+ operationId: 'getSkill',+ method: 'get',+ path: '/skills/{id}',+ tags: [TAG],+ summary: 'Get a skill',+ security: SECURITY,+ pathParams: [{ name: 'id', description: 'The skill id' }],+ responses: [+ { status: 200, description: 'The skill', schema: skillManagementResponseSchema },+ ...errorResponses,+ ],+ },+ {+ operationId: 'updateSkill',+ method: 'patch',+ path: '/skills/{id}',+ tags: [TAG],+ summary: 'Update a skill',+ security: SECURITY,+ pathParams: [{ name: 'id', description: 'The skill id' }],+ body: skillManagementUpdateSchema,+ responses: [+ { status: 200, description: 'The updated skill', schema: skillManagementResponseSchema },+ ...errorResponses,+ {+ status: 409,+ description:+ 'The skill changed since the provided expectedVersion, or the bound account is being deleted',+ schema: z.union([agentManagementErrorSchema, accountDeletionResponseSchema]),+ },+ ],+ },+ {+ operationId: 'listSkillFiles',+ method: 'get',+ path: '/skills/{id}/files',+ tags: [TAG],+ summary: "List a skill's files",+ security: SECURITY,+ pathParams: [{ name: 'id', description: 'The skill id' }],+ responses: [+ { status: 200, description: "The skill's files", schema: skillFileListResponseSchema },+ ...errorResponses,+ ],+ },+ {+ operationId: 'getSkillFile',+ method: 'get',+ path: '/skills/{id}/files/{relativePath}',+ tags: [TAG],+ summary: "Get a skill's file",+ security: SECURITY,+ pathParams: [+ { name: 'id', description: 'The skill id' },+ { name: 'relativePath', description: 'The file path within the skill' },+ ],+ responses: [+ { status: 200, description: 'The file content', schema: skillFileContentSchema },+ ...errorResponses,+ ],+ },+ {+ operationId: 'updateSkillFile',+ method: 'put',+ path: '/skills/{id}/files/{relativePath}',+ tags: [TAG],+ summary: "Create or update a skill's file",+ security: SECURITY,+ pathParams: [+ { name: 'id', description: 'The skill id' },+ { name: 'relativePath', description: 'The file path within the skill' },+ ],+ body: skillFileUpdateSchema,+ responses: [+ { status: 200, description: 'The file was written', schema: skillFileUpdatedSchema },+ ...errorResponses,+ { status: 429, description: 'Too many file-write requests', schema: messageResponseSchema },+ ],+ },+];diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.tsindex d33fec3506..bbc68657b4 100644--- a/packages/api/src/skills/management.ts+++ b/packages/api/src/skills/management.ts@@ -26,14 +26,14 @@ const fields = {category: z.string().optional(),alwaysApply: z.boolean().optional(),};-const frontmatterValue: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>+export const skillFrontmatterValueSchema: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>z.union([z.string(),z.number().finite(),z.boolean(),z.null(),- z.array(frontmatterValue),- z.record(frontmatterValue),+ z.array(skillFrontmatterValueSchema),+ z.record(skillFrontmatterValueSchema),]),);export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };@@ -46,13 +46,13 @@ export const skillManagementUpdateSchema: z.ZodType<SkillManagementUpdate> = zcategory: fields.category,alwaysApply: fields.alwaysApply,body: z.string().optional(),- frontmatter: z.record(frontmatterValue).optional(),+ frontmatter: z.record(skillFrontmatterValueSchema).optional(),expectedVersion: z.number().int().positive(),}).strict().refine((value) => Object.keys(value).length > 1, 'At least one update field is required');-const summarySchema = z.object({+export const skillSummarySchema: z.AnyZodObject = z.object({...fields,id: idSchema,version: z.number().int().positive(),@@ -81,22 +81,32 @@ export type SkillManagementResponse = Pick<| 'frontmatter'> & { id: string };-export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> =- summarySchema.extend({- body: z.string(),- frontmatter: z.record(frontmatterValue).optional(),- });-const fileSchema = z.object({+export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> = z.object({+ ...fields,+ id: idSchema,+ version: z.number().int().positive(),+ fileCount: z.number().int().nonnegative(),+ disableModelInvocation: z.boolean().optional(),+ userInvocable: z.boolean().optional(),+ allowedTools: z.array(z.string()).optional(),+ createdAt: z.string().datetime(),+ updatedAt: z.string().datetime(),+ body: z.string(),+ frontmatter: z.record(skillFrontmatterValueSchema).optional(),+});+export const skillFileSchema: z.AnyZodObject = z.object({relativePath: z.string(),filename: z.string(),mimeType: z.string(),bytes: z.number().int().nonnegative(),});-const fileContentSchema = fileSchema.extend({+export const skillFileContentSchema: z.AnyZodObject = skillFileSchema.extend({content: z.string().optional(),isBinary: z.boolean(),});-const fileUpdateSchema = z.object({ content: z.string().max(1024 * 1024) }).strict();+export const skillFileUpdateSchema: z.AnyZodObject = z+ .object({ content: z.string().max(1024 * 1024) })+ .strict();const listSchema = agentManagementListSchema;type ManagementRequest = Request &@@ -127,7 +137,7 @@ export interface SkillManagementDeps {function projectSkill(body: unknown, detail: boolean): object {const source = z.object({ _id: idSchema }).passthrough().parse(body);- return (detail ? skillManagementResponseSchema : summarySchema).parse({+ return (detail ? skillManagementResponseSchema : skillSummarySchema).parse({...source,id: source._id,});@@ -323,17 +333,17 @@ export function createSkillManagementHandlers(listFiles: wrap(PermissionBits.VIEW, (req, res) =>runHandler(req, res, deps.handlers.listFiles, (body) => ({object: 'list',- data: z.object({ files: z.array(fileSchema) }).parse(body).files,+ data: z.object({ files: z.array(skillFileSchema) }).parse(body).files,})),),getFile: wrap(PermissionBits.VIEW, async (req, res) => {if (Object.keys(req.query).length > 0) return sendError(res, 'invalid_request');return runHandler(req, res, deps.handlers.downloadFile, (body) =>- fileContentSchema.parse(body),+ skillFileContentSchema.parse(body),);}),updateFile: wrap(PermissionBits.EDIT, async (req, res) => {- const parsed = fileUpdateSchema.safeParse(req.body);+ const parsed = skillFileUpdateSchema.safeParse(req.body);if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);const relativePath = resolveSkillFilePathParam(req.params.relativePath);if (relativePath == null || validateRelativePath(relativePath).length > 0)diff --git a/packages/api/tsconfig.openapi.json b/packages/api/tsconfig.openapi.jsonnew file mode 100644index 0000000000..c9abcb3dac--- /dev/null+++ b/packages/api/tsconfig.openapi.json@@ -0,0 +1,16 @@+{+ "extends": "./tsconfig.json",+ "compilerOptions": {+ "baseUrl": ".",+ "module": "commonjs",+ "moduleResolution": "node"+ },+ "ts-node": {+ "esm": false,+ "transpileOnly": true,+ "compilerOptions": {+ "module": "commonjs",+ "moduleResolution": "node"+ }+ }+}diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 151c66ba3b..3ad4c89ff5 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -2989,6 +2989,12 @@ export const configSchema = z.object({message: 'At least one `endpoints` field must be provided.',}).optional(),+ /** Serve the OpenAPI spec and docs for the public Agents API. Off by default. */+ openapi: z+ .object({+ enabled: z.boolean().optional(),+ })+ .optional(),});/**