> ## 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       | Accepted for compatibility. See warning below                                                   |
| `inputType`            | string    | No       | Input type: "PROMPT" or "STRUCTURED"                                                            |
| `canvas`               | boolean   | No       | Enable canvas                                                                                   |
| `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`) 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;
    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
    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.
      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
              deprecated: true
              description: Deprecated. Accepted for compatibility and ignored.
            imageGeneration:
              type: boolean
        actions:
          type: array
          items: 7d19e95b-21e8-417f-995e-24a8f5651c16
        vectorDb:
          type: array
          items: 48adcef5-fb6f-434d-894d-ad23cdeb3651
        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"

````