Before You Start
- Agents API: This is the Agents API with native Vercel AI SDK compatibility.
Overview
The migration process involves two main steps:- Export: Retrieve the agent configuration from the source workspace using the Agent Get API
- Import: Create a new agent in the target workspace using the Agent Create API
Prerequisites
Before you begin, ensure you have:- 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)
- Access to the agent: Your source workspace API key must have access to the agent you want to migrate
- Matching resources in target workspace (if applicable):
- If the target workspace does not have access to the same model, set
modelin 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)
- Skills need to exist in the target workspace. Skill UUIDs from the source workspace are not transferred
- Subagents and workflows need to exist in the target workspace. Their UUIDs from the source workspace are not transferred
- If the target workspace does not have access to the same model, set
Step 1: Export the Agent from Source Workspace
Use the Agent Get API to retrieve the settings available for your agent:Understanding the Response
The Get API returns the following agent settings:name,description,instruction- The agent’s identity and system promptemojiIcon- The emoji icon displayed for the agentmodel- Identifier of the model being used (e.g.,gpt-5-mini-eu)temperature- Creativity setting (0-1)conversationStarters- Suggested prompts for usersinputType- The configured input typeinputFields- Form fields, includingslug,options,fileTypes, andemailDomainwebSearchEnabled,imageGenerationEnabled,canvasEnabled- Capability flagsextendedThinking- Whether extended thinking is enabledactions- Custom integration actionsattachments- UUIDs of attached filesknowledgeFolderIds- UUIDs of connected FoldersskillIds- UUIDs of attached SkillssubAgents- Attached subagents, each withagentIdandrequiresConfirmationworkflowIds- UUIDs of attached workflowsowner- current owner ({ id, name, email }), ornullif unassignedaccess- current sharing when the key has a direct editor or owner grant. See Agent Get API
canvasEnabled is read-only in these endpoints and is not transferred by this migration. owner is not transferred either. access uses ids from the source workspace and is not copied. 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:Field Mapping Reference
Step 3: Create the Agent in Target Workspace
Use the Agent Create API to create the agent in the target workspace:Complete Migration Script
Here’s a complete script that combines all steps:Handling Special Cases
Form Fields
Each field includesslug, options, fileTypes, and emailDomain. Copy inputFields into the Create API request, and omit description when it is null. The Create API rejects null for description. options is [] when a field has no choices, and fileTypes and emailDomain may be null.
Actions (Custom Integrations)
Actions reference integrations that must be enabled in the target workspace. Action UUIDs are specific to each workspace’s integration setup.Attachments
Attachment UUIDs reference files stored in the source workspace. These files are not automatically transferred. To migrate attachments:- Download the files from the source workspace
- Re-upload them to the target workspace using the Upload Attachment API
- Update the agent with the new attachment UUIDs
Skills
Create or import the Skills in the target workspace with the Skills API, then setskillIds on the new agent. Skill IDs from the source workspace are not reused.
Subagents and workflows
Create the subagents and workflows in the target workspace, then setsubAgents and workflowIds on the new agent. IDs from the source workspace are not reused. You can copy requiresConfirmation onto each subagent. An agent set to Direct only cannot be attached, and each workflow must be active.
OAuth Connections
Migrating Multiple Agents
To migrate multiple agents, simply loop through a list of agent IDs: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
- Attach Skills using IDs from the target workspace
- Attach subagents and workflows using IDs from the target workspace
- Configure custom actions/integrations if needed
- Test the agent by sending a message
Limitations
Keep these limitations in mind when planning your migration:
- Attachments are not transferred - Files must be re-uploaded to the target workspace
- Actions may need reconfiguration - Integration action UUIDs are workspace-specific
- OAuth connections require manual setup - Cannot be configured via API
- 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
- Conversation history is not migrated - Only the agent configuration is transferred
- Skills are not transferred - Create the Skills in the target workspace, then attach them with
skillIds - Subagents and workflows are not transferred - Create them in the target workspace, then attach them with
subAgentsandworkflowIds
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.