> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ellaworks.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ellaworks.ai/_mcp/server.

# Importing Agents

If you already have agents in Vapi, Retell, or Telnyx, you can import them into Ellaworks instead of recreating them manually. Ellaworks fetches the remote agent, pulls in any supported tools, creates a local agent record, and links the import to the environment you selected.

Use **single import** when you want to inspect one agent closely before saving it. Use **bulk import** when you need to bring over multiple agents from the same provider in one job.

## What gets imported

For each imported agent, Ellaworks attempts to bring in:

* The agent name and a derived stable key
* Provider configuration and the remote provider agent ID
* Supported tool definitions referenced by the remote agent
* A prompt artifact in the registry you choose during import
* An environment-linked imported deployment record so the agent is immediately tracked in that environment

> **Note**
>
> Imports do not write into the Global (`*`) environment. Choose a specific environment such as `dev`, `staging`, or `prod`.

## Prerequisites

Before starting either import flow, make sure you have:

* A configured provider API key in the target environment
* A prompt registry where imported prompt assets can be created
* Capacity in your current plan for the agents you want to import

The current import providers are:

* Vapi
* Retell
* Telnyx

## Single Import

Single import is built into the regular agent creation flow. It is the best path when you want to import one remote agent and then immediately review or refine its configuration.

#### Open the agent creation flow

Navigate to **Agents** and click **Create Agent**.

#### Choose a provider

Select the deployment provider that already hosts the remote agent. If the provider supports import, Ellaworks will offer an import path in addition to manual creation.

#### Choose import instead of starting from scratch

In the import step, select the remote agent you want to bring into Ellaworks. You must also choose:

* A target environment
* A prompt registry for the imported prompt asset

#### Start the import job

Ellaworks creates an import job for that one remote agent and shows a progress panel while it:

* Connects to the provider
* Fetches the remote agent
* Fetches referenced tools
* Normalizes the provider-specific configuration
* Creates local records in Ellaworks
* Creates and assigns the imported prompt asset

#### Continue to configuration

After the import completes, continue into the configuration steps. At this point you can review the imported values, update names or tags, refine provider settings, and save the agent like any other Ellaworks-managed agent.

### When to use single import

* You are importing one agent at a time
* You want to inspect the imported configuration before finalizing it
* You expect to make edits immediately after the import

## Bulk Import

Bulk import is designed for moving multiple remote agents from the same provider into Ellaworks in one pass.

#### Open the bulk import page

Navigate to **Agents** and open **Import Agents**.

#### Choose a provider

Select the source provider. Ellaworks loads importable remote agents from that provider using the API key configured in the environment you select next.

#### Choose the target environment and prompt registry

Select:

* The environment where the imported agents should be linked
* The prompt registry where imported prompt assets should be created

#### Select remote agents

Browse or filter the remote agent list, then select the agents you want to import. Agents whose derived stable keys already exist in your organization are marked as already imported and cannot be selected again.

#### Start the import job

Ellaworks creates one batch import job and processes each selected remote agent independently. This means one failure does not block the other items in the batch.

#### Review the results

When the job finishes, you will see how many agents completed successfully and how many failed. Failed items can be retried individually or retried as a group.

### Batch limits

* A single bulk import job accepts up to **25 agents**
* The UI also respects your remaining agent quota, so you cannot select more than your current plan allows

## How Ellaworks handles prompts and tools

During import, Ellaworks does more than copy top-level metadata from the provider:

* Referenced tools are fetched from the provider when supported and recreated as Ellaworks tools
* The imported system prompt is stored as a prompt artifact in the registry you selected
* The imported prompt artifact is then assigned back to the imported agent as a prompt reference

This gives you a clean starting point for future edits, versioning, and redeployments from inside Ellaworks.

## Common outcomes and limitations

### Already imported agents

If a remote agent maps to a stable key that already exists in your organization, Ellaworks will block the import instead of overwriting the existing agent.

### Partial success in bulk jobs

Bulk import jobs can finish with a **Partial** result. This usually means some agents imported successfully while one or more others failed validation, hit provider errors, or could not recreate all required resources.

### Missing provider credentials

If the selected environment does not contain an API key for the chosen provider, Ellaworks cannot list or import remote agents from that provider.

### Tool or prompt warnings

Some providers may expose remote configurations that do not map perfectly into Ellaworks. In those cases, the import job can still succeed with warnings, and you can review the imported agent afterward.

## Recommended workflow

Use this pattern if you are migrating a large provider account:

1. Start with a single import for one representative agent.
2. Review the imported prompt, tools, and provider config.
3. Make sure the derived stable key naming works for your team.
4. Once the first import looks correct, switch to bulk import for the remaining agents.

## Next steps

#### [Environment Setup](/environment-setup)

Configure provider credentials and registries before importing

#### [Deploying Agents](/deploying-agents)

Update and redeploy imported agents from inside Ellaworks