> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/getting-started/import-export-an-agent.md).

# Import/Export an Agent

## Overview

**Import/Export** functionality allows you to package entire agents (including all their dependencies) into portable ZIP files. This is essential for agent lifecycle management, collaboration, and deployment automation.

### Why Import/Export?

**Use Cases**:

* **Backup & Restore**: Protect your agent configurations from accidental deletion or corruption
* **Version Control**: Store agent configurations alongside code in Git
* **Environment Migration**: Move agents from development → staging → production
* **Continuous Sync**: Keep agents synchronized across environments with **merge imports**
* **Team Collaboration**: Share agents with team members or customers
* **Disaster Recovery**: Quickly restore agents after system failures
* **Agent Templates**: Create reusable agent templates for similar use cases
* **CI/CD Integration**: Automate agent deployment in your pipeline

### What Gets Exported?

When you export an agent, EDDI packages:

* ✅ Agent configuration (workflow references)
* ✅ All workflows used by the agent
* ✅ All extensions (behavior rules, dictionaries, HTTP calls, outputs, etc.)
* ✅ Version information
* ✅ Configuration metadata
* ✅ **Origin IDs** (resource identifiers for merge tracking)
* ✅ **Prompt snippets** the agent's configurations reference, under `snippets/`
* ✅ **Scheduled triggers** (cron and heartbeat) of the agent, under `schedules/`
* ✅ **Connections** the agent's configurations reference as `${connection:name}`, under `connections/` — the connection *document* only: a name, an auth shape, `${vault:…}` references and an allowlist. Never a resolved secret, and never a grant (linked accounts stay where they were linked). On import a connection is created only when no connection of that name exists yet; an existing one is **never overwritten**, and a document this deployment refuses (a `PER_USER` connection without OIDC, an OAuth one without an active vault) is skipped with the reason logged rather than failing the import. Both cases are counted in an `X-Connections-Skipped` response header. Creating a connection takes `eddi-admin`, exactly as over REST, so an editor's import skips every connection (also counted). See [Connections → Export and import](https://docs.labs.ai/protocols-and-integration/connections.md#export-and-import).

**Every document is scrubbed**, the agent and its workflows included: a Dream job's model `apiKey` or a legacy channel's bot token leaves as `${vault:REDACTED}`. A query parameter whose name marks a credential (`key`, `sig`, `signature`, `accessKey`, …) is redacted in paths and URLs exactly as an editor's read redacts it.

**Workspaces (`eddi.workspaces.enabled=true`).** Export carries what `VIEW` on the agent covers: the configurations its workflow steps name, which were checked when the workflow was written. A URI that sits anywhere else in a workflow (another field of a step's `config`) or only in a parser document needs `VIEW` of its own, or the export (and its preview) answers 403. A prompt snippet travels only when the caller holds `VIEW` on it — a snippet shared for `USE` stays behind. On import and on sync, every workflow written straight to the store passes the same reference check as `POST /workflowstore/workflows`, and a workflow directory without a workflow document is a bad archive (400) rather than a reference kept as the archive wrote it.

**Note**: Conversations and conversation history are **NOT** exported (only configurations). HITL approval-timeout schedules are not exported either: they are safety timers for one pending approval on that deployment, and the import surface refuses to mint them for anybody.

### Selecting What to Export

Three independent query parameters filter the archive. Each is **three-state**: absent means "no selection was expressed for this type" and exports all of it, a value filters, and a present-but-empty value means "none of them".

| Parameter           | Filters                              | Absent           | Empty (`&selectedSnippets=`)    |
| ------------------- | ------------------------------------ | ---------------- | ------------------------------- |
| `selectedResources` | Extension resources (by resource id) | all of them      | all of them (blank = no filter) |
| `selectedSnippets`  | Prompt snippets (by resource id)     | all referenced   | none                            |
| `selectedSchedules` | Scheduled triggers (by schedule id)  | all of the agent | none                            |

`selectedResources` is the exception: it is the older parameter and only a **non-blank** value filters, so a blank one is a full export. Agent and workflow skeletons are always included.

When `selectedResources` omits an extension, the exported workflow **keeps the step that referenced it** — the archive states what the source deployment actually runs. What happens to a reference the archive cannot satisfy is the importer's call, because only it knows the strategy: **`merge` answers it from the target's own copy** of that configuration (and `400`s naming the resource when the target has none), while **`create` drops the step** — there is nothing on a brand-new agent to answer it with — and logs a warning naming it.

> Dropping the step on export instead makes `merge` destructive: it replaces the target's workflow with the archived one, so exporting only the behaviour rules from staging and merging them into production would delete production's own LLM and output steps.

### Archive Retention

A finished archive lives under `tmp/archives/` and is deleted after `eddi.backup.export.retention-minutes` (default `60`). The sweep runs both before each export and on a timer (`eddi.backup.export.sweep-interval`, default `15m`), so an instance that stops exporting still reclaims what it wrote. Read the filename from the `Location` header and download it within the window; afterwards the download answers `404`.

### Import Strategies

EDDI supports three import strategies:

| Strategy             | Behavior                                                                                            | Use Case                             |
| -------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------ |
| **Create** (default) | Always creates a new agent with new IDs                                                             | First-time import, creating copies   |
| **Merge**            | Updates existing resources by matching origin IDs                                                   | Syncing changes across environments  |
| **Upgrade**          | Updates the agent named by `targetAgentId` (required) by structural matching (no origin IDs needed) | Syncing independently created agents |

Merge and Upgrade write a new version over an existing agent. That version is a breaking change unless the request says `compatible=true`; a breaking version leaves the conversations running on the agent where they are, a compatible one lets them follow. See [Promoting an agent by import or sync](https://docs.labs.ai/conversations-and-orchestration/deployment-management-of-agents.md#promoting-an-agent-by-import-or-sync).

### Export/Import Workflow

**First-time import (Create):**

```
DEVELOPMENT EDDI
    ↓
1. Export Agent
   POST /backup/export/agent123?agentVersion=1
   ← Returns: Location /backup/export/My-Agent--agent123-1-<token>.zip
    ↓
2. Download ZIP file
   GET /backup/export/My-Agent--agent123-1-<token>.zip
   ← Receives: My-Agent-agent123-1.zip (needs VIEW on the agent)
    ↓
3. Store in version control / backup / transfer
    ↓
PRODUCTION EDDI
    ↓
4. Upload ZIP file
   POST /backup/import
   Body: (application/zip with ZIP file)
   ← Returns: New agent ID (Location header)
    ↓
5. Deploy imported agent
   POST /administration/production/deploy/{newAgentId}?version=1
```

**Subsequent imports (Merge/Sync):**

```
DEVELOPMENT EDDI  (agent updated since last sync)
    ↓
1. Export latest version
   POST /backup/export/agent123?agentVersion=2
    ↓
2. Download ZIP
    ↓
PRODUCTION EDDI  (has the agent from first import)
    ↓
3. Preview what would change
   POST /backup/import/preview
   ← Returns: list of resources with CREATE/UPDATE/SKIP actions
    ↓
4. Review changes, optionally deselect resources
    ↓
5. Merge import (updates existing, no duplicates)
   POST /backup/import?strategy=merge&selectedResources=origin1,origin2
   ← Returns: Same agent ID, incremented version
    ↓
6. Deploy updated agent
```

### Best Practices

* **Version Your Exports**: Include version numbers in filenames: `customer-support-agent-v2.3.zip`
* **Preview Before Merge**: Always use the preview endpoint before merging to review changes
* **Selective Merge**: Only merge the resources that actually changed to minimize risk
* **Document Changes**: Keep a changelog of what changed between exports
* **Regular Backups**: Schedule automated exports of production agents
* **Test Imports**: Always test imported agents in a test environment first
* **Store Securely**: Keep exports in secure, version-controlled storage (e.g., Git LFS, S3)

### Common Scenarios

**Scenario 1: Promoting to Production (first time)**

```bash
# 1. Export from test environment — the Location header names the ZIP
LOCATION=$(curl -s -D - -o /dev/null -X POST \
  "http://test.eddi.com/backup/export/agent123?agentVersion=1" \
  | grep -i '^location:' | tr -d '\r' | awk '{print $2}')

# 2. Download the ZIP
curl -o agent123-1.zip "http://test.eddi.com${LOCATION}"

# 3. Import to production (creates new agent)
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-1.zip http://prod.eddi.com/backup/import

# 4. Deploy in production
curl -X POST http://prod.eddi.com/administration/production/deploy/{newAgentId}?version=1
```

**Scenario 2: Syncing Updates (merge)**

```bash
# 1. Export updated agent from dev
LOCATION=$(curl -s -D - -o /dev/null -X POST \
  "http://dev.eddi.com/backup/export/agent123?agentVersion=3" \
  | grep -i '^location:' | tr -d '\r' | awk '{print $2}')
curl -o agent123-3.zip "http://dev.eddi.com${LOCATION}"

# 2. Preview what would change in production
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-3.zip http://prod.eddi.com/backup/import/preview

# 3. Merge import — updates existing resources, no duplicates
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-3.zip "http://prod.eddi.com/backup/import?strategy=merge"

# 4. Redeploy
curl -X POST http://prod.eddi.com/administration/production/deploy/{agentId}?version=2
```

**Scenario 3: Selective Merge (only specific resources)**

```bash
# Preview first to get the origin IDs
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-3.zip http://prod.eddi.com/backup/import/preview
# Response includes sourceId for each resource

# Merge only the behavior rules and HTTP calls (by origin ID)
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-3.zip \
  "http://prod.eddi.com/backup/import?strategy=merge&selectedResources=origin-beh-1,origin-http-1"
```

> **`selectedResources` covers every preview row, not just the extensions.** Naming two extension ids deselects everything else the preview listed — including the archive's **scheduled triggers**, which are then not imported. The answer says so: the `201` carries `X-Schedules-Skipped: <count>` whenever the selection left schedules out, and the same count is logged at `INFO`. List the schedule `sourceId`s alongside the extension ones if you want them, or omit the parameter entirely to take the whole archive. Prompt snippets honour the selection too: a snippet row's `sourceId` is the snippet's id in the archive (its file name), and a merge updates a live snippet of the same name only when that id — or the id of the local snippet it matched — is selected. The same filter applies to a create import and to a first-time live sync: a snippet left out of `selectedResources` is not created.

**Scenario 4: Disaster Recovery**

```bash
# Regular automated backup (cron job)
#!/bin/bash
DATE=$(date +%Y%m%d)
LOCATION=$(curl -s -D - -o /dev/null -X POST \
  "http://prod.eddi.com/backup/export/agent123?agentVersion=1" \
  | grep -i '^location:' | tr -d '\r' | awk '{print $2}')
curl -o "backups/agent123-$DATE.zip" "http://prod.eddi.com${LOCATION}"
aws s3 cp "backups/agent123-$DATE.zip" s3://agent-backups/

# Restore after failure
aws s3 cp s3://agent-backups/agent123-20250103.zip ./
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent123-20250103.zip http://prod.eddi.com/backup/import
```

***

## Using the Manager UI

The EDDI Manager provides a guided import wizard accessible from the **Agents** page:

1. **Upload** — Drag-and-drop or browse for a `.zip` export file
2. **Choose Strategy**:
   * **Create New Agent** — Always creates a fresh agent (default)
   * **Merge / Sync** — Updates an existing agent if one with matching origin IDs exists
3. **Preview** (merge only) — Shows a table of all resources with their planned action:
   * 🟢 **New** — Resource doesn't exist locally, will be created
   * 🔵 **Update** — Resource exists locally, will be updated to the imported version
   * ⚪ **Skip** — Resource is identical, no changes needed
4. **Select Resources** — Checkboxes let you pick which resources to merge (all selected by default)
5. **Confirm** — Executes the import

***

## How Merge Tracking Works

When an agent is first imported into an EDDI instance, EDDI stores the **origin ID** of each resource (the ID it had on the source system) in the `DocumentDescriptor`. On subsequent imports with `strategy=merge`:

1. EDDI reads each resource from the ZIP
2. Looks up the origin ID in the local descriptor store (`findByOriginId`)
3. If found → **updates** the existing resource (creating a new version)
4. If not found → **creates** a new resource
5. The agent itself is updated with references to the (possibly new) resource versions

This means the **agent ID stays the same** across merge imports — only the version increments. Deployments, triggers, and integrations that reference the agent ID continue to work without reconfiguration.

**With workspaces enforced, the lookup in step 2 is scoped.** An origin ID is whatever id the exporting instance gave the resource, so every workspace that imported the same archive carries it. Only a resource the importer may **edit**, and — when the import writes into a definite space (the `X-EDDI-Space` header, or the caller's default) — one that **lives in that space**, counts as "found"; a match in another workspace is ignored and the merge creates the importer's own copy instead of overwriting the other team's. Resources from before ownership stamping (no space) are judged by the edit check alone. The preview applies the same rule, and so does a live sync looking for "the agent promoted from this source". With workspaces off nothing changes.

**Administrators are scoped too.** An administrator may edit every resource, but the rule still asks where the import writes: with no `X-EDDI-Space` header that is the administrator's own personal space (or the deployment's default team), and the header only accepts a space the caller is a member of. An administrator who re-imports an archive to update a team's copy therefore has to be a member of that team and send its space in `X-EDDI-Space`; before this rule the merge reached into any workspace's copy, and now it creates a separate copy instead.

***

## API Reference

### Exporting an Agent

Send a **`POST`** request to export. The response `Location` header contains the download URL.

| Element        | Value                                                                                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| HTTP Method    | `POST`                                                                                                                                                                                                       |
| API Endpoint   | `/backup/export/{agentId}?agentVersion={version}`                                                                                                                                                            |
| `agentVersion` | Defaults to `1`, not to the latest version: always pass it                                                                                                                                                   |
| Optional       | `selectedResources`, `selectedSnippets`, `selectedSchedules` (see [Selecting What to Export](#selecting-what-to-export)); `POST /backup/export/{agentId}/preview?agentVersion=N` returns the selectable tree |
| Response       | `Location` header with ZIP download URL                                                                                                                                                                      |

The filename is `{slug}--{agentId}-{agentVersion}-{token}.zip`, where `{slug}` is the slugified agent name and `{token}` is a random hex token (a nameless agent has no slug and no `--`). Read it from the `Location` header rather than constructing it.

**Example:**

```bash
LOCATION=$(curl -s -D - -o /dev/null -X POST \
  "http://localhost:7070/backup/export/agent123?agentVersion=1" \
  | grep -i '^location:' | tr -d '\r' | awk '{print $2}')
# e.g. /backup/export/My-Agent--agent123-1-3f9c0e1a7b2d4c5e8f60718293a4b5c6.zip
# The last segment carries a random token, so the URL cannot be guessed, and the
# download checks VIEW on the exported agent. The file is saved as
# My-Agent-agent123-1.zip (Content-Disposition).

curl -O "http://localhost:7070${LOCATION}"
```

### Importing an Agent (Create)

Upload a ZIP file to create a new agent.

| Element      | Value                                |
| ------------ | ------------------------------------ |
| HTTP Method  | `POST`                               |
| API Endpoint | `/backup/import`                     |
| Content-Type | `application/zip`                    |
| Request Body | ZIP file binary                      |
| Response     | `Location` header with new agent URI |

**Example:**

```bash
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent-export.zip http://localhost:7070/backup/import
```

An agent created this way gets no `identity` and `security.signInterAgentMessages` off, whatever the archive says: the archived keys belong to the agent that was exported, whose private halves are vault entries under its own id. When the archive had signing on, the response says so in an `X-Agent-Signing-Turned-Off` header carrying the reason, and the Manager's import dialog shows it before it closes. To have the new agent sign, an admin generates it a key (`POST /agentstore/agents/{id}/signing-keys`) and turns signing back on; see [architecture.md](https://docs.labs.ai/architecture-and-concepts/architecture.md#cryptographic-agent-identity).

### Preview Merge Import

Dry-run analysis: returns what would change without modifying any data.

| Element      | Value                            |
| ------------ | -------------------------------- |
| HTTP Method  | `POST`                           |
| API Endpoint | `/backup/import/preview`         |
| Content-Type | `application/zip`                |
| Request Body | ZIP file binary                  |
| Response     | JSON with resource diff analysis |

**Response format:**

```json
{
  "sourceAgentId": "original-agent-id-from-source",
  "sourceAgentName": "My Agent",
  "targetAgentId": "local-agent-id",
  "targetAgentName": "My Agent",
  "resources": [
    {
      "sourceId": "original-resource-id",
      "resourceType": "agent",
      "name": "My Agent",
      "action": "UPDATE",
      "targetId": "local-agent-id",
      "targetVersion": 1,
      "matchStrategy": "originId",
      "workflowIndex": -1
    },
    {
      "sourceId": "original-behavior-id",
      "resourceType": "behavior",
      "name": "Greeting Rules",
      "action": "CREATE",
      "targetId": null,
      "targetVersion": null,
      "matchStrategy": null,
      "workflowIndex": 0
    }
  ]
}
```

Upgrade previews additionally populate `sourceContent` and `targetContent` with the raw JSON of each side. The `sourceId` values are what `selectedResources` expects.

**Actions:**

* `CREATE` — No matching local resource found; will be created
* `UPDATE` — Matching local resource found; will be updated
* `SKIP` — Resource is unchanged; will be skipped
* `CONFLICT` — The target's copy was changed on this instance since the last sync (or import) wrote it, and the source changed it too. Written only when named explicitly in `selectedResources`
* `REMOVE` — The target has it and the source no longer does (a workflow step, or a whole workflow). Sync and upgrade previews can emit it; see the [Agent Sync Guide](https://docs.labs.ai/conversations-and-orchestration/agent-sync-guide.md)

### Importing an Agent (Merge)

Update an existing agent by matching origin IDs.

| Element      | Value                                                                                  |
| ------------ | -------------------------------------------------------------------------------------- |
| HTTP Method  | `POST`                                                                                 |
| API Endpoint | `/backup/import?strategy=merge`                                                        |
| Content-Type | `application/zip`                                                                      |
| Request Body | ZIP file binary                                                                        |
| Query Params | `strategy=merge`, optional `selectedResources=id1,id2,...`, optional `compatible=true` |
| Response     | `Location` header with updated agent URI                                               |

**Example (merge all):**

```bash
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent-export.zip "http://localhost:7070/backup/import?strategy=merge"
```

**Example (selective merge):**

```bash
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent-export.zip \
  "http://localhost:7070/backup/import?strategy=merge&selectedResources=origin-id-1,origin-id-2"
```

`selectedResources` is one flat list over **every** row the preview returned — extensions and scheduled triggers alike — so anything not named is left out. A selection of extension ids therefore imports no schedules; the response then carries `X-Schedules-Skipped: <count>` and the same count is logged at `INFO`. Omit the parameter to import the whole archive.

A merge never replaces the local agent's `identity` — its signing keys are this instance's vault entries — so the archive's `security.signInterAgentMessages` is honoured only when the local agent's own newest key is usable. Otherwise the agent is written with signing off and the response carries `X-Agent-Signing-Turned-Off` with the reason (shown by the Manager's import dialog), rather than the whole import being refused over a setting this instance cannot honour.

> **Important:** The agent will not be deployed after import — you must deploy it yourself using the [Deployment API](https://docs.labs.ai/conversations-and-orchestration/deployment-management-of-agents.md).

***

## Upgrade Strategy

In addition to `create` (new agent) and `merge` (by origin ID), EDDI supports an **`upgrade`** strategy that uses structural matching to sync content into an existing agent — even if the agents were created independently (no shared origin IDs):

```bash
# Preview what would change
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent-export.zip \
  "http://localhost:7070/backup/import/preview?targetAgentId=local-agent-id"

# Execute upgrade
curl -X POST -H "Content-Type: application/zip" \
  --data-binary @agent-export.zip \
  "http://localhost:7070/backup/import?strategy=upgrade&targetAgentId=local-agent-id"
```

`targetAgentId` is required: an upgrade without it, or an unknown `strategy`, answers `400`. Optional parameters: `selectedResources` (as for merge), `workflowOrder` (a comma-separated list of the target's workflow ids giving the final order; unlisted workflows follow in their current order, and without it new workflows are appended) and `compatible`.

The upgrade strategy matches resources by **structure** (workflow position, extension type, snippet name) rather than by origin ID. See [Agent Sync](https://docs.labs.ai/conversations-and-orchestration/agent-sync-guide.md) for details on how structural matching works.

### Upgrade response codes

An upgrade (and every `/backup/import/sync` call, which shares the same executor) answers with one of three statuses. **All three are 2xx**, so a client must branch on the status code, not on `response.ok`:

| Status             | Meaning                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `200 OK`           | Source and target already agree. Nothing was written and no agent version was burned.          |
| `201 Created`      | Everything landed and something was written.                                                   |
| `207 Multi-Status` | **Partially applied.** The body's `failures[]` names every resource that could not be written. |

The body is an `UpgradeResult` (`agentUri`, `agentUpdated`, `updated`, `created`, `skipped`, `failures[]`) on all three, and the `Location` header is present on all three.

### Restoring an EDDI 5.x archive

A genuine 5.x export names its agent file `<id>.bot.json` and its workflow file `<id>.package.json` with a `packageExtensions` step list. Both are accepted, and legacy `eddi://` URIs are rewritten to their v6 form on the way in.

### What happens to schedules on import

Imported schedules are repointed at the agent the import just wrote, and everything belonging to the source deployment is reset: `nextFire` is recomputed from the cron expression (an archived one is either long past — firing during the restore — or absent, so it would never fire), `agentVersion` goes back to `0` ("latest"), and the tenant and persistent conversation are cleared. Every write goes through the ordinary schedule API, so the same rules apply as when creating a schedule by hand: a schedule may not run as another user unless you are an administrator, its agent's USE gate is checked, and its cron expression is validated. A schedule that is refused fails the whole import with that status.

**`userId` is source-deployment state too.** It is the identity every fire *acts as*, minted by whichever identity provider the source instance used, so it is kept only when it is already your own and cleared otherwise — the imported schedule then runs as the system scheduler until you assign an owner. Two consequences worth knowing: you can import somebody else's archive without being an administrator, and a **Dream consolidation** schedule arrives with no owner and rejects its first fire with a message naming the field to set. Set `userId` on it after the import (`PUT /schedulestore/schedules/{id}`) — that is deliberately louder than silently consolidating the memories of whichever local user happens to hold the archived id.

With `strategy=merge`, a schedule whose **name** matches one the target agent already has is updated in place rather than added, so re-importing the same agent does not accumulate duplicate cron jobs. Such an update replaces what the schedule *does* — cron, message, agent — but never **who it runs as**: when the archive brings no identity of its own (the usual case, per the paragraph above), the owner already on the target is kept. Otherwise every promotion reset that schedule to the system scheduler, which stops Dream consolidation and drops the schedule's ownership protection. Nor does it change whether the schedule is **enabled**: the update goes through `PUT /schedulestore/schedules/{id}`, which keeps the stored `enabled` value, so a schedule an operator disabled on the target stays disabled (see [Enabling and disabling](https://docs.labs.ai/conversations-and-orchestration/scheduling.md#enabling-and-disabling)). The target's HITL approval timers are excluded from that name matching — they are per-conversation safety timers, never part of an agent's configuration, and the export side leaves them out for the same reason. If the import fails after a schedule was overwritten, the target's original is written back as part of the rollback. The merge preview says so: a schedule whose name the target already uses is listed as `UPDATE` with that schedule's id, not as `CREATE`.

Schedules also honour `selectedResources`: unticking one in the import preview keeps it out. Because that parameter is a single flat list across every preview row, a caller who names only extension ids leaves **all** of them out — the import answers `X-Schedules-Skipped: <count>` and logs the same number at `INFO`, rather than a bare `201` for an agent whose nightly job did not come back. Name the schedule ids too, or leave `selectedResources` off.

### When a merge fails part-way

A merge writes into resources that already exist here. If a later write fails, the import is rolled back as a whole: what it **created** is deleted, and what it **updated** — the agent, its workflows and extensions, and prompt snippets — gets its pre-import content written back as a new version, with the descriptor (name, description, origin) restored alongside. History only ever grows, so the version the failed import wrote stays readable. A resource someone else changed while the import ran is not overwritten by the rollback; the conflict is logged at `WARN` instead.

A merge reads each existing resource before it first overwrites it, because that snapshot is what the rollback writes back. If the read fails, the merge stops there — before overwriting that resource — and fails with `500` naming it, and everything it had already written is rolled back as above. Retry once the store is readable again.

A store can also **refuse** an update: a dictionary whose regular expression does not compile, or httpcalls whose batch settings exceed this deployment's ceiling, is answered `400` with the reason. The merge then fails with that same status and body, rolled back as above, and the refused resource keeps its current version. It never creates a second copy instead: the import used to do that, storing the refused document unchecked next to the original, with the same origin, and pointing the workflow at it. The resource the store refused is named in a `WARN` line in the server log. A prompt snippet is the exception, as for every snippet failure: a refused snippet update costs that snippet, logged at `WARN`, and the agent is still imported.

### Archive limits

An uploaded or synced archive is unpacked under three limits — entry count, bytes per entry, and total bytes, all counted from what is actually decompressed — so a small upload that inflates to gigabytes is refused with `413` and the limit it crossed, instead of filling the disk. The defaults (`10000` entries, 32 MiB per entry, 256 MiB in total) sit far above any real agent export; see `eddi.backup.import.*` in the [configuration reference](https://docs.labs.ai/deployment-and-infrastructure/configuration-reference.md).

An archive that is **malformed** is refused with `400` and the reason, never `500` (which would blame this server for the archive). Two kinds, with different guarantees:

* **The archive itself** — an entry whose path would land outside the extraction directory (`../../x`, "zip-slip"), an entry name that is not a valid path, corrupt compressed data, or a truncated upload (including one cut off after its last complete entry, before the ZIP's central directory). These are found while unpacking, before anything is imported, so **nothing is written**.
* **The agent, a workflow or an extension config is not valid JSON** — the import stops with `400`, and whatever it had already created (snippets, connections, earlier resources) is rolled back, as for any failed import.

A **snippet or connection file** that is not valid JSON is *not* fatal: like any snippet or connection the importer cannot use, it is skipped with a warning in the log, and the rest of the archive is imported.

**One document is one resource.** An archive file is named by resource id, so every reference to that id — the same workflow named twice in the agent, two spellings of one URI, or several versions of one extension — reads the same file, and the import (and a preview or sync) parses and writes it once; every reference then names the one resource written for it. A workflow directory holding **more than one** workflow document is a bad archive (`400`): only one of them could ever be the workflow the agent names.

## Live Sync (Without ZIP)

If both EDDI instances are reachable over HTTP, you can skip the ZIP step entirely and sync directly between instances. See the [**Agent Sync Guide**](https://docs.labs.ai/conversations-and-orchestration/agent-sync-guide.md) for the full workflow.

***

## See Also

* [Agent Sync Guide](https://docs.labs.ai/conversations-and-orchestration/agent-sync-guide.md) — Live instance-to-instance sync and upgrade imports
* [Deployment Management](https://docs.labs.ai/conversations-and-orchestration/deployment-management-of-agents.md) — Deploying agents after import
* [Secrets Vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md) — How API keys are scrubbed and re-vaulted during import
