> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Update API

> Update an existing agent programmatically

Updates an existing agent in your workspace. Only the fields you provide will be updated, allowing for partial updates without affecting other configuration.

## Before You Start

* **API key scope**: Requires an API key with the **Agent API** scope and access to the agent you want to update.
* **Legacy Assistants API**: This is the new Agents API with native Vercel AI SDK compatibility. If you're using the legacy Assistants API, see the [migration guide](/en/developer/agents-api/assistant-to-agent-migration).
* **Draft only**: Updates are applied to the agent's **draft** only. The active (published) version remains unchanged until the agent is published from the Langdock UI.

## Base URL

```
https://api.langdock.com/agent/v1/update
```

<Warning>
  **Dedicated deployments**

  Replace `api.langdock.com` with `<your-deployment-url>/api/public` in all requests.
</Warning>

## Update Behavior

The update endpoint uses partial update semantics with specific behavior for different field types:

* **Partial updates** - Only fields provided in the request are updated; omitted fields remain unchanged
* **Array fields replace** - `actions`, `inputFields`, `conversationStarters`, `attachments`, and `knowledgeFolderIds` completely replace existing values when provided
* **Empty arrays** - Send `[]` to remove all actions/fields/attachments
* **Null handling** - Send `null` for `emoji` to clear it. For `description` and `instruction`, send an empty string `""` to clear them
* **Unchanged fields** - Fields not included in the request retain their current values

## Parameters

Set any of the parameters below to overwrite the agent's current settings. Fields you omit stay unchanged. Only `agentId` is required.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `agentId` | string | Yes | UUID of the agent to update |
| `name` | string | No | Agent name (1-80 characters) |
| `description` | string | No | Description (max 800 chars, `""` to clear) |
| `emoji` | string | No | Emoji icon (max 16 chars, null to clear) |
| `instruction` | string | No | System prompt (max 50000 chars, `""` to clear) |
| `model` | string | No | `id` from the [Models API](/en/developer/agents-api/agent-models). Unique names and Anthropic aliases stay valid |
| `creativity` | number | No | Temperature between 0 and 1 |
| `conversationStarters` | string\[] | No | Suggested prompts, max 20, each 1-255 chars (replaces existing) |
| `actions` | array | No | Actions (replaces existing) |
| `inputFields` | array | No | Form fields (replaces existing) |
| `attachments` | string\[] | No | Up to 50 attachment UUIDs (replaces existing) |
| `knowledgeFolderIds` | string\[] | No | Folder UUIDs (replaces existing) |
| `webSearch` | boolean | No | Enable web search |
| `imageGeneration` | boolean | No | Enable image generation |
| `dataAnalyst` | boolean | No | Accepted for compatibility. See warning below |
| `inputType` | string | No | Input type: "PROMPT", "STRUCTURED", "INTEGRATION", "SCHEDULED", or "WEBHOOK" |
| `extendedThinking` | boolean | No | Enable extended thinking mode |

<Warning>
  The `dataAnalyst` parameter is deprecated and has no effect. Requests that include it still succeed for backward compatibility, but Langdock ignores the value and does not enable file or code execution. Omit this parameter from new integrations.
</Warning>

<Warning>
  Array fields (`actions`, `inputFields`, `conversationStarters`, `attachments`, `knowledgeFolderIds`) are **replaced entirely**, not merged. Always provide the complete desired array, including any existing items you want to keep.
</Warning>

### Actions Configuration

Each action in the `actions` array should contain:

* `actionId` (required) - UUID of the action
* `requiresConfirmation` (optional) - Whether to require user confirmation before executing (default: true)

New ids must belong to an integration enabled in your workspace. Ids already on the draft follow the validation rules below.

### Input Fields Configuration

For `inputFields` array structure, see the [Create Agent API](/en/developer/agents-api/agent-create) documentation.

## Examples

### Updating Basic Properties

```javascript theme={null}
const axios = require("axios");

async function updateAgentName() {
  const response = await axios.patch(
    "https://api.langdock.com/agent/v1/update",
    {
      agentId: "550e8400-e29b-41d4-a716-446655440000",
      name: "Advanced Document Analyzer",
      description: "Analyzes documents with enhanced capabilities",
      creativity: 0.7
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Agent updated:", response.data.message);
}
```

## Validation Rules

The API enforces several validation rules:

* **Agent access** - Your API key must have access to the agent
* **Workspace match** - Agent must belong to the same workspace as your API key
* **Model** - If provided, must be in your workspace's active models list
* **Actions** - If provided, the array replaces the draft list. Omit an id to remove it.
* **Draft action ids** - Missing or soft-deleted ids already on the draft are dropped. Unavailable ids already on the draft stay.
* **New action ids** - Must exist and belong to integrations enabled in your workspace. Otherwise the request returns 400 with `missingActionIds` or `unavailableActionIds`.
* **Attachments** - If provided, must exist in your workspace and not be deleted
* **Folders** - If provided, must exist in your workspace and not be deleted
* **Name** - If provided, must be between 1-80 characters
* **Description** - If provided, maximum 800 characters
* **Instruction** - If provided, maximum 50000 characters
* **Creativity** - If provided, must be between 0 and 1

## Response Format

### Success Response (200 OK)

```typescript theme={null}
{
  status: "success";
  message: "Agent updated successfully";
  agent: {
    id: string;
    name: string;
    description: string | null;
    instruction: string | null;
    emojiIcon: string | null;
    model: string | null;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED" | "INTEGRATION" | "SCHEDULED" | "WEBHOOK";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      type: "TEXT" | "MULTI_LINE_TEXT" | "NUMBER" | "CHECKBOX" | "FILE" | "SELECT" | "MULTI_SELECT" | "DATE" | "EMAIL";
      label: string;
      description: string | null;
      required: boolean;
      order: number;
    }>;
    attachments: string[];
    knowledgeFolderIds: string[];
    owner: {
      id: string;
      name: string | null;
      email: string;
    } | null;
    createdAt: string;
    updatedAt: string;
  };
  preservedUnavailableActionIds?: string[];
}
```

`preservedUnavailableActionIds` is included only when the request kept unavailable ids that were already on the draft.

## Error Handling

```typescript theme={null}
try {
  const response = await axios.patch('https://api.langdock.com/agent/v1/update', ...);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error('Invalid parameters or resource not found:', error.response.data.message);
        break;
      case 401:
        console.error('Invalid or missing API key');
        break;
      case 403:
        console.error('Insufficient permissions - no access to this agent');
        break;
      case 404:
        console.error('Agent not found or API key does not have access');
        break;
      case 429:
        console.error('Rate limit exceeded');
        break;
      case 500:
        console.error('Server error');
        break;
    }
  }
}
```

## Best Practices

<Info>
  **Preserving existing values**: When updating array fields like `actions` or `attachments`, always include existing items you want to keep, as the entire array is replaced.
</Info>

1. **Fetch before update** - If you need to preserve existing array values, fetch the current agent first. GET returns the published version when one exists, otherwise the draft.
2. **Incremental updates** - Update only the fields that need to change
3. **Validate attachments** - Ensure attachment UUIDs are valid before including them
4. **Keep draft actions** - Resubmit every action id you want to keep. Missing ids already on the draft are dropped. Unavailable ids already on the draft stay.
5. **Handle errors gracefully** - Implement proper error handling for validation failures

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>


## OpenAPI

````yaml PATCH /agent/v1/update
openapi: 3.0.0
info:
  title: Langdock API
  version: 3.0.0
servers:
  - url: https://api.langdock.com
    description: Production
security:
  - bearerAuth: []
paths:
  /agent/v1/update:
    patch:
      tags:
        - Agent Build
      summary: Updates an existing agent
      description: >-
        Updates an existing agent in your workspace. Updates apply to the draft.
        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.
      operationId: updateAgentV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - agentId
                  properties:
                    agentId:
                      type: string
                      format: uuid
                - $ref: '#/components/schemas/AssistantWriteRequest'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - message
                  - agent
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                    example: Agent updated successfully
                  agent:
                    $ref: '#/components/schemas/AssistantDetails'
                  preservedUnavailableActionIds:
                    type: array
                    items:
                      type: string
                      format: uuid
                    description: >-
                      Unavailable action ids already on the draft that were
                      kept. Omitted when empty.
components:
  schemas:
    AssistantWriteRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
          description: Name of the agent or assistant
        description:
          type: string
          maxLength: 800
          description: >-
            Description of what the agent or assistant does. Send an empty
            string to clear it during an update.
        instruction:
          type: string
          maxLength: 50000
          description: >-
            System prompt or instructions. Send an empty string to clear it
            during an update.
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
            - INTEGRATION
            - SCHEDULED
            - WEBHOOK
          description: Input type
        emoji:
          type: string
          nullable: true
          maxLength: 16
          description: Emoji icon
        model:
          type: string
          description: >-
            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:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature for response generation
        conversationStarters:
          type: array
          maxItems: 20
          items:
            type: string
            minLength: 1
            maxLength: 255
          description: Suggested prompts
        actions:
          type: array
          items:
            $ref: '#/components/schemas/AssistantActionRequest'
          description: >-
            Actions that the agent or assistant can use. On update, the array
            replaces the draft list.
        inputFields:
          type: array
          items:
            $ref: '#/components/schemas/AssistantInputFieldRequest'
          description: Form fields for STRUCTURED input
        webSearch:
          type: boolean
          description: Enable web search
        imageGeneration:
          type: boolean
          description: Enable image generation
        dataAnalyst:
          type: boolean
          deprecated: true
          description: Deprecated. Accepted for compatibility and ignored.
        extendedThinking:
          type: boolean
          description: Enable extended thinking
        attachments:
          type: array
          maxItems: 50
          items:
            type: string
            format: uuid
          description: Attachment UUIDs
        knowledgeFolderIds:
          type: array
          items:
            type: string
            format: uuid
          description: Folder UUIDs
    AssistantDetails:
      type: object
      required:
        - id
        - name
        - description
        - instruction
        - emojiIcon
        - model
        - temperature
        - conversationStarters
        - inputType
        - webSearchEnabled
        - imageGenerationEnabled
        - canvasEnabled
        - extendedThinking
        - actions
        - inputFields
        - attachments
        - knowledgeFolderIds
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
        name:
          type: string
          description: Name of the agent
        description:
          type: string
          nullable: true
          description: Description of what the agent does
        instruction:
          type: string
          nullable: true
          description: System prompt/instructions for the agent
        emojiIcon:
          type: string
          nullable: true
          description: Emoji icon for the agent
        model:
          type: string
          nullable: true
          description: Model ID to use (see Models for Agent API)
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: Temperature/creativity setting for response generation
        conversationStarters:
          type: array
          items:
            type: string
          description: Array of suggested prompts to help users get started
        inputType:
          type: string
          enum:
            - PROMPT
            - STRUCTURED
            - INTEGRATION
            - SCHEDULED
            - WEBHOOK
          description: Input type for the agent
        webSearchEnabled:
          type: boolean
          description: Whether web search capability is enabled
        imageGenerationEnabled:
          type: boolean
          description: Whether image generation capability is enabled
        canvasEnabled:
          type: boolean
          description: Whether canvas capability is enabled
        extendedThinking:
          type: boolean
          description: >-
            Whether extended thinking is enabled. Only supported on models that
            expose this capability; enabling it on an unsupported model returns
            a 400 error.
        actions:
          type: array
          items:
            type: object
            required:
              - actionId
              - requiresConfirmation
            properties:
              actionId:
                type: string
                format: uuid
                description: >-
                  UUID of a live action. Missing and soft-deleted ids are
                  omitted. Live unavailable actions remain.
              requiresConfirmation:
                type: boolean
                description: Whether user confirmation is required before executing
          description: >-
            Live actions on the returned version. Missing and soft-deleted ids
            are omitted. Live unavailable actions remain.
        inputFields:
          type: array
          items:
            type: object
            required:
              - type
              - label
              - description
              - required
              - order
            properties:
              type:
                type: string
                enum:
                  - TEXT
                  - MULTI_LINE_TEXT
                  - NUMBER
                  - CHECKBOX
                  - FILE
                  - SELECT
                  - MULTI_SELECT
                  - DATE
                  - EMAIL
                description: Field type
              label:
                type: string
                description: Display label for the field
              description:
                type: string
                nullable: true
                description: Help text for the field
              required:
                type: boolean
                description: Whether the field is required
              order:
                type: integer
                minimum: 0
                description: Display order (0-indexed)
          description: Array of form field definitions (for STRUCTURED input type)
        attachments:
          type: array
          items:
            type: string
            format: uuid
          description: Array of attachment UUIDs associated with the agent
        knowledgeFolderIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of Folder UUIDs associated with the agent
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the agent was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the agent was last updated
    AssistantActionRequest:
      type: object
      required:
        - actionId
      properties:
        actionId:
          type: string
          format: uuid
          description: >-
            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:
          type: boolean
          default: true
          description: Whether to require user confirmation before executing
    AssistantInputFieldRequest:
      type: object
      required:
        - slug
        - type
        - label
        - order
      properties:
        slug:
          type: string
          minLength: 1
          maxLength: 64
          description: Unique identifier for the field
        type:
          type: string
          enum:
            - TEXT
            - MULTI_LINE_TEXT
            - NUMBER
            - CHECKBOX
            - FILE
            - SELECT
            - MULTI_SELECT
            - DATE
            - EMAIL
          description: Field type
        label:
          type: string
          minLength: 1
          maxLength: 255
          description: Display label for the field
        description:
          type: string
          maxLength: 512
          description: Help text for the field
        required:
          type: boolean
          default: false
          description: Whether the field is required
        order:
          type: integer
          minimum: 0
          description: Display order
        options:
          type: array
          default: []
          items:
            type: string
            minLength: 1
            maxLength: 255
          description: Options for SELECT and MULTI_SELECT fields
        fileTypes:
          type: string
          nullable: true
          maxLength: 255
          description: Allowed file types for FILE fields
        emailDomain:
          type: string
          nullable: true
          description: Allowed email domain for EMAIL fields
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.