> ## 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

<Info>
  **⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

<Info>
  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/assistants-api/assistant-to-agent-migration).
</Info>

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

<Info>
  Updates are applied to the agent's **draft** only. The active (published) version remains unchanged until the agent is published from the Langdock UI.
</Info>

<Info>
  Requires an API key with the `AGENT_API` scope and access to the agent you want to update.
</Info>

## 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`, and `attachments` 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

## Request 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 500 chars, `""` to clear)                                                      |
| `emoji`                | string    | No       | Emoji icon (max 16 chars, null to clear)                                                        |
| `instruction`          | string    | No       | System prompt (max 40000 chars, `""` to clear)                                                  |
| `model`                | string    | No       | Model identifier (deployment name from the [Models API](/en/developer/agents-api/agent-models)) |
| `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       | Attachment UUIDs (replaces existing)                                                            |
| `webSearch`            | boolean   | No       | Enable web search                                                                               |
| `imageGeneration`      | boolean   | No       | Enable image generation                                                                         |
| `dataAnalyst`          | boolean   | No       | Enable code interpreter                                                                         |
| `inputType`            | string    | No       | Input type: "PROMPT" or "STRUCTURED"                                                            |
| `canvas`               | boolean   | No       | Enable canvas                                                                                   |
| `extendedThinking`     | boolean   | No       | Enable extended thinking mode                                                                   |

<Warning>
  Array fields (`actions`, `inputFields`, `conversationStarters`, `attachments`) 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 from an enabled integration
* `requiresConfirmation` (optional) - Whether to require user confirmation before executing (default: true)

### 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, must belong to integrations enabled in your workspace
* **Attachments** - If provided, must exist in your workspace and not be deleted
* **Name** - If provided, must be between 1-80 characters
* **Description** - If provided, maximum 500 characters
* **Instruction** - If provided, maximum 40000 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;
    instruction: string;
    emojiIcon: string;
    model: string;
    temperature: number;
    conversationStarters: string[];
    inputType: "PROMPT" | "STRUCTURED";
    webSearchEnabled: boolean;
    imageGenerationEnabled: boolean;
    codeInterpreterEnabled: boolean;
    canvasEnabled: boolean;
    extendedThinking: boolean;
    actions: Array<{
      actionId: string;
      requiresConfirmation: boolean;
    }>;
    inputFields: Array<{
      slug: string;
      type: string;
      label: string;
      description: string;
      required: boolean;
      order: number;
      options: string[];
      fileTypes: string[] | null;
      emailDomain: string | null;
    }>;
    attachments: string[];
    createdAt: string;
    updatedAt: string;
  };
}
```

## 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 configuration first
2. **Incremental updates** - Update only the fields that need to change
3. **Validate attachments** - Ensure attachment UUIDs are valid before including them
4. **Test actions** - Verify actions belong to enabled integrations before updating
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
security:
  - bearerAuth: []
paths:
  /agent/v1/update:
    patch:
      tags:
        - Agent Build
      summary: Updates an existing agent
      description: Updates an existing agent in your workspace.
      operationId: updateAgentV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - agentId
                  properties:
                    agentId:
                      type: string
                      format: uuid
                - $ref: '#/components/schemas/Assistant'
      responses:
        '200':
          description: Agent updated successfully
components:
  schemas:
    Assistant:
      type: object
      required:
        - name
        - instructions
      properties:
        name:
          type: string
          maxLength: 64
        description:
          type: string
          maxLength: 256
        instructions:
          type: string
          maxLength: 16384
        temperature:
          type: number
          minimum: 0
          maximum: 1
        model:
          type: string
          maxLength: 64
        capabilities:
          type: object
          properties:
            webSearch:
              type: boolean
            dataAnalyst:
              type: boolean
            imageGeneration:
              type: boolean
        actions:
          type: array
          items: 1bf2826f-77f1-463b-8e46-3f0f76872032
        vectorDb:
          type: array
          items: 4eac90fd-6825-4d77-98ed-79cf9672bab5
        knowledgeFolderIds:
          type: array
          items:
            type: string
        attachmentIds:
          type: array
          items:
            type: string
            format: uuid
          description: Array of UUID strings identifying attachments for this message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"

````