> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Updates an agent's information. Partial updates are supported. You can update only the name, role, description, instructions, personaId, toolIds and knowledge. ## OpenAPI ````yaml https://api-trial.cognigy.ai/swagger/openapi.json patch /agents/{id} openapi: 3.0.3 info: contact: email: support@example.com name: API Support description: API for managing agents and related resources license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: http://swagger.io/terms/ title: Agents API version: '1.0' servers: - url: https://api-trial.cognigy.ai/v1 security: - ApiKey: [] tags: - name: Agents - name: Brand personas - name: Tools - name: Built-in tools - name: Skills - name: Built-in skills - name: MCP servers - name: Tool references paths: /agents/{id}: patch: tags: - Agents summary: Update an agent description: >- Updates an agent's information. Partial updates are supported. You can update only the name, role, description, instructions, personaId, toolIds and knowledge. parameters: - description: The unique identifier for the agent. in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/internal_agents.UpdateAgentRequest' description: Agent update data required: true x-originalParamName: agent responses: '200': content: application/json: schema: $ref: '#/components/schemas/internal_agents.UpdateAgentResponse' description: OK '400': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest description: Invalid request body or validation error '403': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden description: Access denied '404': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound description: Agent not found '409': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict description: Another agent in this project already uses the requested name '500': content: application/json: schema: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError description: Internal server error components: schemas: internal_agents.UpdateAgentRequest: properties: agentType: description: |- AgentType: send "text" or "voice" to change the agent's authored modality. A missing key or an explicit null is "no change"; an empty string is rejected, because an agent cannot be un-typed on purpose. enum: - text - voice type: string description: type: string disabledToolReferenceIds: description: >- DisabledToolReferenceIds switches tools off for this agent without changing how they reach it: the runtime withholds them from the LLM, the resource keeps its parameters, and the Tools tab keeps showing the row. Accepts a reference on EITHER route — a tool attached directly, or one bundled in a skill this agent has hired. A skill's own bundle is never edited by this: it is shared by every agent that hires the skill, so the per-agent switch is recorded here instead. Replaces the whole set, like ToolReferenceIds does. Absent = no change, `[]` = enable everything. A reference the agent cannot reach by either route is stored as sent and ignored at execution time. items: type: string type: array guardrails: allOf: - $ref: '#/components/schemas/internal_agents.GuardrailsRequest' description: >- Guardrails: send a non-null object to set or update the block. Same "cannot clear via PATCH" caveat as LLMConfig. Unlike LLMConfig, replacement is scoped to each sub-object rather than to the block. To toggle one inner safety field, resend the whole SafetySettings object: a toggle left out of it is stored off (unlike create, where it defaults on). Sending only `safetySettings` leaves `dataPrivacy` intact, and sending only `dataPrivacy` leaves `safetySettings` intact. Sending neither (`{}`) changes nothing. hooks: description: |- Hooks replaces the whole block. Send `null` or `{"preTurn": []}` to remove it; a missing key leaves it unchanged. Unlike LLMConfig and Guardrails, this block can be cleared through PATCH. type: object image: description: >- Image is the agent's avatar: either a URL or a base64 data URI. Optional, like AgentType above: a missing key or an explicit null is "no change". Unlike AgentType, an explicit empty string IS meaningful — it clears the avatar — since an agent without one is a valid, expressible state. type: string imageOptimizedFormat: description: >- ImageOptimizedFormat reports whether Image is stored in Cognigy's optimized image format. Same "nil = no change" semantics as Image; the two are set together, never independently. type: boolean instructions: description: |- Instructions: same rules as on create. A stored value over the limit that is sent back unchanged is accepted. type: string knowledge: allOf: - $ref: '#/components/schemas/internal_agents.PatchKnowledgeRequest' description: |- Knowledge uses field-level merge (RFC 7396 JSON Merge Patch). Each inner field independently distinguishes absent / explicit null / value. See PatchKnowledgeRequest. largeLanguageModelReferenceId: type: string llmConfig: allOf: - $ref: '#/components/schemas/internal_agents.LLMConfigRequest' description: |- LLMConfig: send a non-null object to set or replace the override. A missing key OR an explicit null is treated as "no change" — this endpoint cannot currently clear an existing override. Removing the override requires a separate path (or a future revision that wires PartialUpdateInput.ClearLLMConfig from a raw-body presence check). localeReferenceId: type: string name: description: 'Name: same rules as on create.' type: string personaReferenceId: type: string realtimeVoice: description: >- RealtimeVoice: one of the gpt-live-1 voices (alloy, ash, ballad, beacon, bossa, cedar, cinder, coral, delta, echo, gleam, marin, meridian, quartz, ripple, sage, shimmer, stone, tempo, verse, vesper, willow) sets it, null resets to "marin"; missing is no change; others are 400. type: string role: description: >- Role: absent or explicit null leaves the stored value alone; a string replaces it (send "" to clear). Same rules as on create. type: string skillReferenceIds: items: type: string type: array toolReferenceIds: items: type: string type: array voiceLargeLanguageModelReferenceId: description: >- VoiceLargeLanguageModelReferenceId: a UUID sets it, "" clears it; missing or null is no change. type: string voicePromptTemplate: description: >- VoicePromptTemplate: a string sets it, null resets to the product default; missing is no change; empty or over 32 KiB is rejected with 400. type: string type: object internal_agents.UpdateAgentResponse: properties: agentType: description: >- AgentType is the modality the agent was authored for. Always present: an agent stored without one — every agent that predates the field — reads back as "text", because it was authored when chat was the only thing an agent could be. enum: - text - voice example: voice type: string createdAt: type: integer createdBy: example: 507f1f77bcf86cd799439011 type: string description: type: string disabledToolReferenceIds: items: type: string type: array guardrails: $ref: '#/components/schemas/internal_agents.GuardrailsResponse' hooks: $ref: '#/components/schemas/internal_agents.HooksResponse' id: example: 507f1f77bcf86cd799439011 type: string image: type: string imageOptimizedFormat: type: boolean instructions: type: string knowledge: $ref: '#/components/schemas/internal_agents.KnowledgeResponse' largeLanguageModelReferenceId: type: string lastChangedAt: type: integer lastChangedBy: example: 507f1f77bcf86cd799439011 type: string llmConfig: $ref: '#/components/schemas/internal_agents.LLMConfigResponse' localeReferenceId: type: string name: type: string organisationId: example: 507f1f77bcf86cd799439011 type: string personaReferenceId: type: string projectId: example: 507f1f77bcf86cd799439011 type: string realtimeVoice: description: >- RealtimeVoice is the gpt-live-1 voice; absent means the default ("marin"). type: string referenceId: type: string role: type: string skillReferenceIds: items: type: string type: array toolReferenceIds: items: type: string type: array voiceLargeLanguageModelReferenceId: description: >- VoiceLargeLanguageModelReferenceId links a realtime (V2V) LLM for voice sessions. Optional UUID; text turns never use it. type: string voicePromptTemplate: description: >- VoicePromptTemplate is the agent's own template; absent means the product default. type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailBadRequest: properties: detail: example: request body validation failed type: string errors: items: $ref: >- #/components/schemas/github_com_cognigy_ai-agents-v2_internal_middleware.FieldError type: array instance: example: /v1/{resource} type: string status: example: 400 type: integer title: example: Bad Request type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailForbidden: properties: detail: example: 'access denied: insufficient permissions' type: string instance: example: /v1/{resource}/{id} type: string status: example: 403 type: integer title: example: Forbidden type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailNotFound: properties: detail: example: the requested resource does not exist type: string instance: example: /v1/{resource}/{id} type: string status: example: 404 type: integer title: example: Not Found type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailConflict: properties: detail: example: a resource with this identifier already exists type: string instance: example: /v1/{resource} type: string status: example: 409 type: integer title: example: Conflict type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object github_com_cognigy_ai-agents-v2_internal_middleware.ProblemDetailInternalError: properties: detail: example: internal server error type: string instance: example: /v1/{resource} type: string status: example: 500 type: integer title: example: Internal Server Error type: string traceId: example: api--a4d2f126-bec4-4544-a049-7c0cf08524ed type: string type: example: about:blank type: string type: object internal_agents.GuardrailsRequest: properties: dataPrivacy: $ref: '#/components/schemas/internal_agents.DataPrivacyRequest' safetySettings: $ref: '#/components/schemas/internal_agents.SafetySettingsRequest' type: object internal_agents.PatchKnowledgeRequest: properties: cognigyParameters: $ref: >- #/components/schemas/internal_agents.Patchable-internal_agents_PatchCognigyRAGParametersDTO context: $ref: '#/components/schemas/internal_agents.Patchable-string' onSearchFailure: $ref: '#/components/schemas/internal_agents.Patchable-string' ragMode: $ref: '#/components/schemas/internal_agents.Patchable-string' ragType: $ref: '#/components/schemas/internal_agents.Patchable-string' type: object internal_agents.LLMConfigRequest: properties: maxOutputTokens: type: integer reasoningEffort: description: >- ReasoningEffort controls the model's internal "thinking" budget. Allowed: "none", "minimal", "low", "medium", "high", "xhigh". Reasoning tokens are billed as completion tokens and reported as a subset of them. type: string temperature: type: number type: object internal_agents.GuardrailsResponse: properties: dataPrivacy: $ref: '#/components/schemas/internal_agents.DataPrivacyResponse' safetySettings: $ref: '#/components/schemas/internal_agents.SafetySettingsResponse' type: object internal_agents.HooksResponse: properties: preTurn: items: $ref: '#/components/schemas/internal_agents.PreTurnHook' type: array type: object internal_agents.KnowledgeResponse: properties: cognigyParameters: $ref: '#/components/schemas/internal_agents.CognigyRAGParametersDTO' context: type: string onSearchFailure: type: string ragMode: type: string ragType: type: string type: object internal_agents.LLMConfigResponse: properties: maxOutputTokens: type: integer reasoningEffort: type: string temperature: type: number type: object github_com_cognigy_ai-agents-v2_internal_middleware.FieldError: properties: field: type: string message: type: string type: object internal_agents.DataPrivacyRequest: properties: contactProfilesOption: description: |- ContactProfilesOption is one of "none", "completeProfile", "profileMemoriesOnly" or "selectedProfileFields". example: completeProfile type: string selectedProfileFields: description: |- SelectedProfileFields names the profile keys to inject, and is read only under "selectedProfileFields". Names are not validated against the project's Profile Schema — that schema is owned by service-profiles and can change after the agent is saved, so a name that no longer resolves simply injects nothing. items: type: string type: array type: object internal_agents.SafetySettingsRequest: properties: avoidCopyrightInfringements: type: boolean avoidHarmfulContent: type: boolean avoidUngroundedContent: type: boolean preventJailbreakAndManipulation: type: boolean type: object internal_agents.Patchable-internal_agents_PatchCognigyRAGParametersDTO: properties: present: type: boolean value: $ref: '#/components/schemas/internal_agents.PatchCognigyRAGParametersDTO' type: object internal_agents.Patchable-string: properties: present: type: boolean value: type: string type: object internal_agents.DataPrivacyResponse: properties: contactProfilesOption: example: completeProfile type: string selectedProfileFields: items: type: string type: array type: object internal_agents.SafetySettingsResponse: properties: avoidCopyrightInfringements: type: boolean avoidHarmfulContent: type: boolean avoidUngroundedContent: type: boolean preventJailbreakAndManipulation: type: boolean type: object internal_agents.PreTurnHook: properties: handler: $ref: '#/components/schemas/internal_agents.HookHandler' type: object internal_agents.CognigyRAGParametersDTO: properties: language: type: string stores: items: type: string type: array topK: type: integer type: object internal_agents.PatchCognigyRAGParametersDTO: properties: language: $ref: '#/components/schemas/internal_agents.Patchable-string' stores: $ref: '#/components/schemas/internal_agents.Patchable-array_string' topK: $ref: '#/components/schemas/internal_agents.Patchable-int' type: object internal_agents.HookHandler: properties: flowReferenceId: type: string kind: type: string type: object internal_agents.Patchable-array_string: properties: present: type: boolean value: items: type: string type: array type: object internal_agents.Patchable-int: properties: present: type: boolean value: type: integer type: object securitySchemes: ApiKey: description: '[Production] API key for production authentication' in: header name: X-API-Key type: apiKey ````