---
title: "Updates an existing agent"
method: PATCH
path: "/agent/v1/update"
tags: ["Agent Build"]
---

# Updates an existing agent

`PATCH /agent/v1/update`

## Request

- Base URL: `https://api.langdock.com`
- URL: `https://api.langdock.com/agent/v1/update`
- Auth: HTTP bearer

Updates an existing agent in your workspace. Configuration updates apply to the draft; access changes take effect immediately without publishing. When `actions` is provided, the array replaces the draft list. Ids already on the draft that are missing or soft-deleted are dropped. Ids already on the draft whose integration is not enabled stay. A brand-new missing or unavailable id returns 400. The success body includes `preservedUnavailableActionIds` only when unavailable draft ids were kept.

## Request body

- object
  - `agentId` string, uuid, required
  - `access` AgentAccessUpdate: Sharing changes under the Agent API scope and the key owner's workspace sharing permissions. Updating access requires an explicit editor or owner key grant. New user and group grants send in-app notifications after commit; repeated grants, role changes, and revocations do not. No email is sent. Omitted targets and empty arrays leave access unchanged. Owner and API-key grants cannot be changed. Admin-managed sharing cannot be updated.
    - `users` AgentAccessChange[]: User grants to add, change, or revoke. New grants require active users in the same workspace. Revocation also supports inactive or former users. IDs must be unique.
      - `id` string, uuid, required: User or group UUID.
      - `role` 'user' | 'editor' | 'null', nullable, required: Use or edit access. Set null to revoke this direct grant.
    - `groups` AgentAccessChange[]: Group grants to add, change, or revoke. Groups must belong to the workspace and be manageable by the key owner unless workspace permissions allow sharing with any group. IDs must be unique.
      - `id` string, uuid, required: User or group UUID.
      - `role` 'user' | 'editor' | 'null', nullable, required: Use or edit access. Set null to revoke this direct grant.
    - `workspace` 'user' | 'editor' | 'null', nullable: Workspace-wide role, or null to revoke workspace access.
  - `name` string: Name of the agent or assistant
  - `description` string: Description of what the agent or assistant does. Send an empty string to clear it during an update.
  - `instruction` string: System prompt or instructions. Send an empty string to clear it during an update.
  - `inputType` 'PROMPT' | 'STRUCTURED' | 'INTEGRATION' | 'SCHEDULED' | 'WEBHOOK': Input type
  - `emoji` string, nullable: Emoji icon
  - `model` string: id from GET /agent/v1/models. Unique deployment names and Anthropic aliases stay valid. When several accessible rows share a name, send the UUID id.
  - `creativity` number: Temperature for response generation
  - `conversationStarters` string[]: Suggested prompts
  - `actions` AssistantActionRequest[]: Actions that the agent or assistant can use. On update, the array replaces the draft list.
    - `actionId` string, uuid, required: UUID of the action. Create requires an enabled workspace integration. Update also accepts ids already on the draft as described on PATCH /agent/v1/update.
    - `requiresConfirmation` boolean: Whether to require user confirmation before executing
  - `inputFields` AssistantInputFieldRequest[]: Form fields for STRUCTURED input
    - `slug` string, required: Unique identifier for the field
    - `type` 'TEXT' | 'MULTI_LINE_TEXT' | 'NUMBER' | 'CHECKBOX' | 'FILE' | 'SELECT' | 'MULTI_SELECT' | 'DATE' | 'EMAIL', required: Field type
    - `label` string, required: Display label for the field
    - `description` string: Help text for the field
    - `required` boolean: Whether the field is required
    - `order` integer, required: Display order
    - `options` string[]: Options for SELECT and MULTI_SELECT fields
    - `fileTypes` string, nullable: Allowed file types for FILE fields
    - `emailDomain` string, nullable: Allowed email domain for EMAIL fields
  - `webSearch` boolean: Enable web search
  - `imageGeneration` boolean: Enable image generation
  - `dataAnalyst` boolean: Deprecated. Accepted for compatibility and ignored.
  - `extendedThinking` boolean: Enable extended thinking
  - `attachments` string[]: Attachment UUIDs
  - `knowledgeFolderIds` string[]: Folder UUIDs

## Response `200`

Agent updated successfully

- object
  - `status` 'success', required
  - `message` string, required
  - `agent` AssistantDetails, required
    - `access` AgentAccessConfiguration: Current direct sharing settings, returned only when the API key has an explicit editor or owner grant on the agent. Owner and API-key grants are excluded. Sharing is independent of the agent's published version.
      - `users` AgentAccessGrant[], required
        - `id` string, uuid, required
        - `role` 'user' | 'editor', required
      - `groups` AgentAccessGrant[], required
        - `id` string, uuid, required
        - `role` 'user' | 'editor', required
      - `workspace` 'user' | 'editor' | 'null', nullable, required
      - `sharingManagedByAdmin` boolean, required: Whether sharing is managed by an administrator and cannot be changed through this API.
    - `id` string, uuid, required: Unique identifier for the agent
    - `name` string, required: Name of the agent
    - `description` string, nullable, required: Description of what the agent does
    - `instruction` string, nullable, required: System prompt/instructions for the agent
    - `emojiIcon` string, nullable, required: Emoji icon for the agent
    - `model` string, nullable, required: Model ID to use (see Models for Agent API)
    - `temperature` number, required: Temperature/creativity setting for response generation
    - `conversationStarters` string[], required: Array of suggested prompts to help users get started
    - `inputType` 'PROMPT' | 'STRUCTURED' | 'INTEGRATION' | 'SCHEDULED' | 'WEBHOOK', required: Input type for the agent
    - `webSearchEnabled` boolean, required: Whether web search capability is enabled
    - `imageGenerationEnabled` boolean, required: Whether image generation capability is enabled
    - `canvasEnabled` boolean, required: Whether canvas capability is enabled
    - `extendedThinking` boolean, required: Whether extended thinking is enabled. Only supported on models that expose this capability; enabling it on an unsupported model returns a 400 error.
    - `actions` object[], required: Live actions on the returned version. Missing and soft-deleted ids are omitted. Live unavailable actions remain.
      - `actionId` string, uuid, required: UUID of a live action. Missing and soft-deleted ids are omitted. Live unavailable actions remain.
      - `requiresConfirmation` boolean, required: Whether user confirmation is required before executing
    - `inputFields` object[], required: Array of form field definitions (for STRUCTURED input type)
      - `type` 'TEXT' | 'MULTI_LINE_TEXT' | 'NUMBER' | 'CHECKBOX' | 'FILE' | 'SELECT' | 'MULTI_SELECT' | 'DATE' | 'EMAIL', required: Field type
      - `label` string, required: Display label for the field
      - `description` string, nullable, required: Help text for the field
      - `required` boolean, required: Whether the field is required
      - `order` integer, required: Display order (0-indexed)
    - `attachments` string[], required: Array of attachment UUIDs associated with the agent
    - `knowledgeFolderIds` string[], required: Array of Folder UUIDs associated with the agent
    - `createdAt` string, date-time, required: Timestamp when the agent was created
    - `updatedAt` string, date-time, required: Timestamp when the agent was last updated
  - `preservedUnavailableActionIds` string[]: Unavailable action ids already on the draft that were kept. Omitted when empty.

## Changes

- **2026-11-03** `c62bf90b4013`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langdock/apis/langdock-api/changes/agent/v1/update/patch.md)

---

[API](https://skmtc.dev/langdock/apis/langdock-api.md) - [All operations](https://skmtc.dev/langdock/apis/langdock-api/llms.txt) - [OpenAPI document](https://skmtc.dev/langdock/apis/langdock-api/revisions/c62bf90b4013?raw)