> ## Documentation Index > Fetch the complete documentation index at: https://docs.nuwacom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Update an agent. Changes are written to the draft; the published version stays untouched until the agent is re-published in the app (`hasUnpublishedChanges` flags the drift). Omitted fields keep their current value. Built-in nuwacom system agents cannot be updated. ## OpenAPI ````yaml /openapi.yaml patch /api/v1/spaces/{spaceId}/agents/{agentId} openapi: 3.1.0 info: title: Nuwacom API description: API for Nuwacom application version: 1.0.0 servers: - url: https://{customer-tenant}.nuwacom.ai description: Nuwacom API security: - bearerAuth: [] paths: /api/v1/spaces/{spaceId}/agents/{agentId}: patch: tags: - Agents summary: Update an agent description: >- Update an agent. Changes are written to the draft; the published version stays untouched until the agent is re-published in the app (`hasUnpublishedChanges` flags the drift). Omitted fields keep their current value. Built-in nuwacom system agents cannot be updated. operationId: patchApiV1SpacesBySpaceIdAgentsByAgentId parameters: - in: path name: spaceId schema: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: ID of the space the agent belongs to. required: true - in: path name: agentId schema: type: string format: uuid description: Unique ID of the agent. required: true requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Display name of the agent. description: type: string description: Short description of what the agent does. systemInstruction: anyOf: - type: string description: >- System prompt / instructions that define the agent's behavior. nullable: true conversationStarters: type: array items: type: object properties: id: type: string format: uuid description: >- Unique ID of the conversation starter. Generated server-side when omitted. text: type: string description: >- The prompt text sent to the agent when the starter is clicked. label: type: string description: >- Short display label. Falls back to the text when omitted. type: enum: - prompt - text description: Kind of starter. Defaults to "text". default: text required: - text description: >- Suggested prompts shown to users when starting a chat with the agent. welcomeMessage: type: object properties: text: type: object additionalProperties: type: string required: - text description: >- Welcome message shown when a chat with the agent starts, keyed by locale (e.g. { "text": { "en-US": "Hi!" } }). model: anyOf: - type: string description: >- Model ID used for completions with this agent (e.g. "azure-gpt-4o"). See [List all AI models](/api-reference/ai/list-all-ai-models). nullable: true temperature: anyOf: - type: number description: >- Sampling temperature applied to completions with this agent. nullable: true attachmentIds: type: array items: type: string format: uuid description: >- KB asset IDs (files uploaded via [Upload an asset](/api-reference/assets/upload-an-asset)) attached as agent knowledge. folderIds: type: array items: type: string format: uuid description: Knowledge folder IDs whose contents the agent can search. contentIds: type: array items: type: string format: uuid description: nuwacom document/content IDs attached as agent knowledge. allowUploads: type: boolean description: >- Whether users may attach file uploads when chatting with the agent. allowUrls: type: boolean description: Whether users may attach URLs when chatting with the agent. enableFollowUpMessages: type: boolean description: >- Whether the agent suggests follow-up messages after each response. categoryId: anyOf: - type: number description: ID of the library category the agent is assigned to. nullable: true voiceId: anyOf: - type: string format: uuid description: ID of the tone-of-voice profile applied to the agent. nullable: true appEnabled: type: boolean description: >- Whether the agent is available inside the nuwacom app. Defaults to true. embedEnabled: type: boolean description: >- Whether the agent is published as an external, embeddable chat widget. When enabling this, set `embedOptions.domainWhitelist` before publishing (publishing an embed-enabled agent without an allowlist is rejected). Defaults to false. embedOptions: type: object properties: domainWhitelist: type: array items: type: string showSources: type: boolean allowVoiceInput: type: boolean allowFileUpload: type: boolean themeMode: enum: - dark - light lightTheme: type: object properties: backgroundColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true primaryColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true required: [] darkTheme: type: object properties: backgroundColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true primaryColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true required: [] required: [] description: >- External embed widget options (allowed domains, theme, upload/voice toggles, source display). On update the provided object fully replaces the current embed options. actions: type: array items: type: object properties: integration: type: string minLength: 1 description: >- Provider the action belongs to: "nuwacom" for built-in tools, "MCP" for an MCP server, or a connected integration type (e.g. "gmail", "outlook"). key: type: string minLength: 1 description: >- Action key within the integration. For `nuwacom`, one of the built-in, app-supported tool keys: `WEB_SEARCH`, `RETRIEVE_FROM_KNOWLEDGE_BASE`, `DISPLAY_DOCUMENT`, `DISPLAY_SLIDES`, `DISPLAY_EMAIL`, `IMAGE_GENERATION`, `VIDEO_GENERATION`. For an integration or MCP server, the exact tool key it exposes (e.g. `GMAIL_SEND_EMAIL`). requiresConfirmation: type: boolean description: >- Whether the user must confirm before the action runs. Defaults to false. defaultValues: type: object additionalProperties: {} description: >- Preset parameter values applied whenever the action runs. Defaults to {}. integrationId: anyOf: - type: string format: uuid description: >- ID of the specific connected integration instance to use for this action (for provider integrations). nullable: true mcpClientId: anyOf: - type: string format: uuid description: >- ID of the MCP client that exposes this action. Required for "MCP" actions. nullable: true required: - integration - key description: >- Actions/tools the agent can use. On update the provided array fully replaces the agent's current draft actions (send [] to remove all). Publish the agent to make action changes take effect for the Completion API. required: [] responses: '200': description: Agent updated successfully. content: application/json: schema: type: object properties: id: type: string format: uuid description: >- Unique ID of the agent. Use it with the Completion API (`agentId` option) to chat with the agent. spaceId: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: ID of the space the agent belongs to. name: type: string description: type: string systemInstruction: anyOf: - type: string nullable: true conversationStarters: type: array items: type: object properties: id: type: string format: uuid description: >- Unique ID of the conversation starter. Generated server-side when omitted. text: type: string description: >- The prompt text sent to the agent when the starter is clicked. label: type: string description: >- Short display label. Falls back to the text when omitted. type: enum: - prompt - text description: Kind of starter. Defaults to "text". default: text required: - text welcomeMessage: anyOf: - type: object additionalProperties: {} nullable: true model: anyOf: - type: string nullable: true temperature: anyOf: - type: number nullable: true attachmentIds: type: array items: type: string format: uuid folderIds: type: array items: type: string format: uuid contentIds: type: array items: type: string format: uuid allowUploads: type: boolean allowUrls: type: boolean enableFollowUpMessages: type: boolean categoryId: anyOf: - type: number nullable: true voiceId: anyOf: - type: string nullable: true appEnabled: type: boolean embedEnabled: type: boolean description: >- Whether the agent is published as an external, embeddable chat widget. embedId: anyOf: - type: string nullable: true description: Identifier used to embed the agent as an external widget. embedOptions: type: object properties: domainWhitelist: type: array items: type: string showSources: type: boolean allowVoiceInput: type: boolean allowFileUpload: type: boolean themeMode: enum: - dark - light lightTheme: type: object properties: backgroundColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true primaryColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true required: [] darkTheme: type: object properties: backgroundColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true primaryColor: anyOf: - type: object properties: h: type: number s: type: number v: type: number a: type: number required: - h - s - v - a nullable: true required: [] required: [] description: External embed widget options (draft state). actions: type: array items: type: object properties: id: type: string format: uuid description: Unique ID of the action. integration: type: string key: type: string requiresConfirmation: type: boolean defaultValues: type: object additionalProperties: {} integrationId: anyOf: - type: string nullable: true mcpClientId: anyOf: - type: string nullable: true required: - id - integration - key - requiresConfirmation - defaultValues - integrationId - mcpClientId description: Actions/tools configured on the agent (draft state). isSystemAgent: type: boolean description: >- true for built-in nuwacom system agents (cannot be updated or deleted). published: type: boolean description: >- Whether a published version of the agent exists. Publishing happens in the nuwacom app. hasUnpublishedChanges: type: boolean description: >- true when the draft differs from the published version (or nothing has been published yet). createdAt: type: string updatedAt: type: string required: - id - spaceId - name - description - systemInstruction - conversationStarters - welcomeMessage - model - temperature - attachmentIds - folderIds - contentIds - allowUploads - allowUrls - enableFollowUpMessages - categoryId - voiceId - appEnabled - embedEnabled - embedId - embedOptions - actions - isSystemAgent - published - hasUnpublishedChanges - createdAt - updatedAt '400': description: Invalid request body. '403': description: >- The caller lacks permission to update agents in this space, or the agent is a system agent. '404': description: Agent not found in the provided space. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````