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

> How to migrate agents between Langdock workspaces using the Agents API

This guide explains how to migrate agents from one Langdock workspace to another using the Agents API. This is useful when you want to replicate agent configurations across different workspaces, move agents during organizational restructuring, or create backup copies of your agents.

## Before You Start

* **Agents API**: This is the Agents API with native Vercel AI SDK compatibility.

## Overview

The migration process involves two main steps:

1. **Export**: Retrieve the agent configuration from the source workspace using the [Agent Get API](/en/developer/agents-api/agent-get)
2. **Import**: Create a new agent in the target workspace using the [Agent Create API](/en/developer/agents-api/agent-create)

## Prerequisites

Before you begin, ensure you have:

1. **Two API keys with the Agent API scope**:
   * One API key for the **source workspace** (where the agent currently exists)
   * One API key for the **target workspace** (where you want to migrate the agent)
2. **Access to the agent**: Your source workspace API key must have access to the agent you want to migrate
3. **Matching resources in target workspace** (if applicable):
   * If the target workspace does not have access to the same model, set `model` in the script to an available deployment name before migration
   * If the agent uses custom actions, those integrations must be enabled in the target workspace
   * Attachments need to be re-uploaded separately (they are not transferred automatically)

## Step 1: Export the Agent from Source Workspace

Use the **Agent Get API** to retrieve the settings available for your agent:

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

async function getAgentFromSource(agentId, sourceApiKey) {
  const response = await axios.get(
    "https://api.langdock.com/agent/v1/get",
    {
      params: {
        agentId: agentId
      },
      headers: {
        Authorization: `Bearer ${sourceApiKey}`
      }
    }
  );

  return response.data.agent;
}
```

### Understanding the Response

The Get API returns the following agent settings:

* `name`, `description`, `instruction` - The agent's identity and system prompt
* `emojiIcon` - The emoji icon displayed for the agent
* `model` - Identifier of the model being used (e.g., `gpt-5-mini-eu`)
* `temperature` - Creativity setting (0-1)
* `conversationStarters` - Suggested prompts for users
* `inputType` - The configured input type
* `inputFields` - Display properties for form fields. The response does not include the `slug`, `options`, `fileTypes`, or `emailDomain` values required to recreate them
* `webSearchEnabled`, `imageGenerationEnabled`, `canvasEnabled` - Capability flags
* `extendedThinking` - Whether extended thinking is enabled
* `actions` - Custom integration actions
* `attachments` - UUIDs of attached files
* `knowledgeFolderIds` - UUIDs of connected Folders
* `owner` - current owner (`{ id, name, email }`), or `null` if unassigned

`canvasEnabled` is read-only in these endpoints and is not transferred by this migration. `owner` is not transferred either. The key owner becomes the owner in the target workspace.

## Step 2: Transform the Configuration

The Get API response uses slightly different field names than the Create API expects. You need to map the fields:

```javascript theme={null}
function transformForCreate(sourceAgent) {
  return {
    // Basic information
    name: sourceAgent.name,
    description: sourceAgent.description || undefined,
    emoji: sourceAgent.emojiIcon || undefined,
    instruction: sourceAgent.instruction || undefined,

    // Settings
    model: sourceAgent.model,
    creativity: sourceAgent.temperature,
    inputType: sourceAgent.inputType,
    conversationStarters: sourceAgent.conversationStarters || [],

    // Capabilities
    webSearch: sourceAgent.webSearchEnabled,
    imageGeneration: sourceAgent.imageGenerationEnabled,
    extendedThinking: sourceAgent.extendedThinking,
    knowledgeFolderIds: sourceAgent.knowledgeFolderIds || [],

    // Note: input fields, actions, and attachments require special handling (see below)
  };
}
```

### Field Mapping Reference

| Get API Response Field | Create API Request Field |
| - | - |
| `name` | `name` |
| `description` | `description` |
| `emojiIcon` | `emoji` |
| `instruction` | `instruction` |
| `model` | `model` |
| `temperature` | `creativity` |
| `inputType` | `inputType` |
| `conversationStarters` | `conversationStarters` |
| `webSearchEnabled` | `webSearch` |
| `imageGenerationEnabled` | `imageGeneration` |
| `extendedThinking` | `extendedThinking` |
| `knowledgeFolderIds` | `knowledgeFolderIds` |
| `actions` | `actions` |
| `attachments` | `attachments` |

## Step 3: Create the Agent in Target Workspace

Use the **Agent Create API** to create the agent in the target workspace:

```javascript theme={null}
async function createAgentInTarget(agentConfig, targetApiKey) {
  const response = await axios.post(
    "https://api.langdock.com/agent/v1/create",
    agentConfig,
    {
      headers: {
        Authorization: `Bearer ${targetApiKey}`,
        "Content-Type": "application/json"
      }
    }
  );

  return response.data.agent;
}
```

## Complete Migration Script

Here's a complete script that combines all steps:

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

// Configuration
const SOURCE_API_KEY = "your-source-workspace-api-key";
const TARGET_API_KEY = "your-target-workspace-api-key";
const AGENT_ID_TO_MIGRATE = "550e8400-e29b-41d4-a716-446655440000";

async function migrateAgent() {
  try {
    // Step 1: Get agent from source workspace
    console.log("Fetching agent from source workspace...");
    const getResponse = await axios.get(
      "https://api.langdock.com/agent/v1/get",
      {
        params: { agentId: AGENT_ID_TO_MIGRATE },
        headers: { Authorization: `Bearer ${SOURCE_API_KEY}` }
      }
    );
    
    const sourceAgent = getResponse.data.agent;
    console.log(`Found agent: "${sourceAgent.name}"`);

    // Step 2: Transform configuration for Create API
    const createConfig = {
      name: sourceAgent.name,
      description: sourceAgent.description || undefined,
      emoji: sourceAgent.emojiIcon || undefined,
      instruction: sourceAgent.instruction || undefined,
      model: sourceAgent.model,
      creativity: sourceAgent.temperature,
      inputType: sourceAgent.inputType,
      conversationStarters: sourceAgent.conversationStarters || [],
      webSearch: sourceAgent.webSearchEnabled,
      imageGeneration: sourceAgent.imageGenerationEnabled,
      extendedThinking: sourceAgent.extendedThinking,
      knowledgeFolderIds: sourceAgent.knowledgeFolderIds || [],
      // Note: input fields, actions, and attachments excluded - see "Handling Special Cases"
    };

    // Remove undefined values
    Object.keys(createConfig).forEach(key => {
      if (createConfig[key] === undefined) {
        delete createConfig[key];
      }
    });

    // Step 3: Create agent in target workspace
    console.log("Creating agent in target workspace...");
    const createResponse = await axios.post(
      "https://api.langdock.com/agent/v1/create",
      createConfig,
      {
        headers: {
          Authorization: `Bearer ${TARGET_API_KEY}`,
          "Content-Type": "application/json"
        }
      }
    );

    const newAgent = createResponse.data.agent;
    console.log(`Migration successful!`);
    console.log(`New agent ID: ${newAgent.id}`);
    console.log(`Agent name: ${newAgent.name}`);
    
    return newAgent;

  } catch (error) {
    if (error.response) {
      console.error(`Error ${error.response.status}: ${JSON.stringify(error.response.data)}`);
    } else {
      console.error("Error:", error.message);
    }
    throw error;
  }
}

migrateAgent();
```

## Handling Special Cases

### Form Fields

The Get API response does not include the `slug`, `options`, `fileTypes`, or `emailDomain` values required by the Create API. Recreate form fields manually in the target workspace.

### Actions (Custom Integrations)

Actions reference integrations that must be enabled in the target workspace. Action UUIDs are specific to each workspace's integration setup.

<Warning>
  Exclude actions from the initial migration and manually configure them in the target workspace after the agent is created.
</Warning>

### Attachments

Attachment UUIDs reference files stored in the source workspace. These files are not automatically transferred.

**To migrate attachments**:

1. Download the files from the source workspace
2. Re-upload them to the target workspace using the [Upload Attachment API](/en/developer/agents-api/upload-attachments)
3. Update the agent with the new attachment UUIDs

### OAuth Connections

<Warning>
  Pre-selected OAuth connections are **not supported via the API**. Users must configure OAuth connections through the Langdock UI after migration.
</Warning>

## Migrating Multiple Agents

To migrate multiple agents, simply loop through a list of agent IDs:

```javascript theme={null}
const AGENT_IDS = [
  "agent-uuid-1",
  "agent-uuid-2",
  "agent-uuid-3"
];

async function migrateMultipleAgents() {
  const results = [];
  
  for (const agentId of AGENT_IDS) {
    try {
      console.log(`\nMigrating agent: ${agentId}`);
      const newAgent = await migrateAgent(agentId);
      results.push({ 
        sourceId: agentId, 
        targetId: newAgent.id, 
        status: "success" 
      });
    } catch (error) {
      results.push({ 
        sourceId: agentId, 
        status: "failed", 
        error: error.message 
      });
    }
  }
  
  console.log("\n=== Migration Summary ===");
  console.table(results);
}
```

## Post-Migration Checklist

After migrating an agent, verify the following in the target workspace:

* Agent appears in the Agents list with correct name and emoji
* Description and instructions are correctly transferred
* Model is available in the target workspace
* Conversation starters are present
* Capabilities (web search, image generation, etc.) are correctly enabled
* Input fields are properly configured (for STRUCTURED input type)
* Manually configure any OAuth connections through the UI
* Re-upload and attach any necessary files
* Configure custom actions/integrations if needed
* Test the agent by sending a message

## Limitations

<Info>
  Keep these limitations in mind when planning your migration:
</Info>

1. **Attachments are not transferred** - Files must be re-uploaded to the target workspace
2. **Actions may need reconfiguration** - Integration action UUIDs are workspace-specific
3. **OAuth connections require manual setup** - Cannot be configured via API
4. **Model access must match** - The Create API rejects a model that is not available in the target workspace. Set an available deployment name before migration
5. **Conversation history is not migrated** - Only the agent configuration is transferred

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


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