> 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/reference/agent-sync-architecture.md).

# Agent Sync Architecture

> Transport-agnostic pipeline for import, export, upgrade, and live sync of EDDI agent configurations.

## Overview

EDDI agents are complex configuration trees: an `AgentConfiguration` contains references to `WorkflowConfiguration`s, which contain `WorkflowStep`s referencing extension resources (LLM configs, behavior rules, HTTP calls, etc.), plus `PromptSnippet`s.

The agent sync architecture provides:

1. **Selective export** — choose which resources to include in a ZIP
2. **Structural matching** — deterministic pairing of source/target resources
3. **Content diffing** — preview exactly what will change before committing
4. **In-place upgrade** — update existing resources without breaking URI references
5. **Live sync** — sync between instances without ZIP intermediary

## Architecture

```
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  IResourceSource │     │ StructuralMatcher│     │  UpgradeExecutor │
│  (transport)     │────▶│  (analysis)      │────▶│  (write)         │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                         │                        │
   ┌────┴────┐              ImportPreview            Store updates
   │         │           (resource diffs)         (version increments)
   ▼         ▼
ZipResource  RemoteApi
Source       ResourceSource
```

## Matching Algorithm

Resources are matched from source to target using a deterministic, structural approach:

| Resource Type  | Matching Strategy                                                                                                                        | Rationale                                                                                                 |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Agent**      | Direct (by `targetAgentId` parameter); for a live sync without it, the agent whose descriptor records the source agent as its `originId` | User explicitly selects the target, or it is the copy an earlier promotion made                           |
| **Workflows**  | Position index (0-based) in agent's workflow list                                                                                        | Workflows have a defined order; position is stable                                                        |
| **Extensions** | Extension reference key — `<stepType>#<occurrence>/<path>`, e.g. `eddi://ai.labs.llm#0/config`                                           | Position within the workflow is stable, and the occurrence ordinal keeps two steps of the same type apart |
| **Snippets**   | `PromptSnippet.name` (natural key)                                                                                                       | Names are unique by convention                                                                            |

Extension keys all come from one scan (`WorkflowExtensions.scan`) that the export ZIP, a remote instance and the local target each use, which is what makes the two sides join. Three properties of that key matter:

* **The URI is read from the step's `config` map, not its `extensions` map.** `config.uri` is where the engine itself looks; `extensions` carries nested things such as the parser's `dictionaries` list, whose entries have a `config.uri` of their own and are scanned as well.
* **A document can name resources too.** A parser document names its own dictionaries; `WorkflowExtensions.scanDocument` keys each under the document (`eddi://ai.labs.parser#0/config/@document/extensions/dictionaries/0/config`), so they are matched, created and updated like the workflow's own. Writing one repoints the parser document that names it, never a workflow step. A resource the workflow already names is keyed once, under the workflow's key.
* **A step type may repeat.** A workflow with a pre-LLM and a post-LLM `eddi://ai.labs.httpcalls` step keeps an entry for each, told apart by the `#<occurrence>` ordinal, instead of collapsing onto one.

### Why Not Match by ID?

Source and target resources have different IDs (generated by their respective datastores). Matching by origin ID only works when an agent was previously imported from the same source — structural matching works for independently-created agents too.

## Data Flow

### Import (ZIP)

```
1. User uploads ZIP → RestImportService.importAgent()
2. ZIP extracted to temp dir → ZipResourceSource created
3. If strategy=upgrade:
   a. StructuralMatcher.buildPreview() → ImportPreview (content diffs)
   b. UpgradeExecutor.executeUpgrade() → updates target resources in-place
4. If strategy=merge:
   a. Resources matched by origin ID (DocumentDescriptor.originId), updated in place
      or created; rolled back as a whole on failure
5. If strategy=create:
   a. Standard import (creates all new resources)
6. ZipResourceSource.close() → cleans up temp dir
```

### Export (Selective)

```
1. User requests preview → RestExportService.previewExport()
2. Returns ExportPreview (resource tree with selectability flags)
3. User selects resources → exportAgent(selectedResourceIds)
4. Only selected resources included in ZIP (agent + workflow skeletons always included)
```

### Live Sync

```
1. RemoteApiResourceSource reads from remote EDDI REST API — every document
   through SecretScrubber, so the pipeline sees what an export archive would
2. With no targetAgentId: the agent whose descriptor records the source agent
   as its originId is the target (409 if several); none → first promotion
3. Same StructuralMatcher + UpgradeExecutor pipeline
4. No ZIP intermediary — direct instance-to-instance sync
```

## Key Design Decisions

### Upgrade = Content Sync

An upgrade doesn't replace the target agent's resource tree — it syncs content into existing resources. This means:

* Target resource IDs are preserved
* URI references (workflow → extension) are updated, not rewritten
* Version numbers are incremented (creating new versions, not overwriting)
* External references to these resources (deployments, triggers) continue to work

### What the preview compares

The matcher compares what the executor would write, not what the source holds:

* **References rewritten onto the target.** The source's workflow steps are pointed at the target's resources, and the source agent's workflows and `identity` replaced by the target's, before comparing — otherwise the two name each other's ids and never agree. A step or workflow the target has and the source does not becomes a `REMOVE` row.
* **Secrets put back.** Wherever the source has a scrubbed placeholder or a vault reference and the target has a value at the same place, the target's value is used (`ScrubbedSecrets`). The row's `sourceContent` is that merged document.
* **Local edits detected.** `DocumentDescriptor.syncedVersion` records the version a sync or import last wrote. A target version past it that differs from the synced version in more than its own secrets (compared with the target's secrets put back into the synced version) was changed locally, and if the source changed it too it is a `CONFLICT` instead of an `UPDATE`.

### Structural changes

`UpgradeExecutor` adopts the source workflow's steps when the workflow row is an `UPDATE`. Before writing anything it decides whether that adoption can succeed (`adoptionBlocker`): every source step must name either a resource the target already has at that key, or one this run creates because it was served and selected. Only then is a resource for an added step created — deciding it afterwards left an unreferenced copy behind whenever the adoption was refused. A workflow the target lacks is created after its resources, with its steps repointed at them. Agent-level settings come from the agent row's merged `sourceContent`; the target's workflow list and identity are kept, and nothing is written when the result equals the current agent.

### Extension Type Registry

`UpgradeExecutor` uses an `ExtensionStoreOps` registry to map extension type names to their configuration class and store operations. Adding a new extension type requires one entry in `resolveExtensionOps()` — no duplicated switch blocks.

### Transport Agnostic

The `IResourceSource` interface is the only transport abstraction. All downstream logic (`StructuralMatcher`, `UpgradeExecutor`, `ImportPreview`) operates on `IResourceSource` records, not on ZIP files or HTTP responses.

## ZIP Directory Structure

```
<rootDir>/
  <agentId>.agent.json
  <agentId>.descriptor.json
  <workflowId>/
    <version>/
      <workflowId>.workflow.json       (or .package.json for legacy v5)
      <workflowId>.descriptor.json
      <extId>.langchain.json           (LLM config)
      <extId>.httpcalls.json           (HTTP calls)
      <extId>.behavior.json            (rules)
      <extId>.regulardictionary.json   (dictionary)
      <extId>.parser.json              (parser document; absent from archives written before it travelled)
      <extId>.property.json            (property setter)
      <extId>.output.json              (output templates)
      <extId>.mcpcalls.json            (MCP calls)
      <extId>.rag.json                 (RAG config)
      <extId>.descriptor.json          (per-extension)
  snippets/
    <snippetId>.snippet.json
  schedules/
    <scheduleId>.schedule.json
  connections/
    <connectionId>.connection.json   (ZIP import/export, and a live sync's first promotion, which imports this archive — later syncs do not carry connections)
```

## API Endpoints

### Export

| Method | Path                                             | Purpose                            |
| ------ | ------------------------------------------------ | ---------------------------------- |
| `POST` | `/backup/export/{agentId}/preview`               | Resource tree for selective export |
| `POST` | `/backup/export/{agentId}?selectedResources=...` | Export ZIP with selected resources |

### Import

| Method | Path                                                | Purpose                    |
| ------ | --------------------------------------------------- | -------------------------- |
| `POST` | `/backup/import/preview?targetAgentId=...`          | Preview with content diffs |
| `POST` | `/backup/import?strategy=upgrade&targetAgentId=...` | Execute upgrade import     |

### Live Sync

| Method | Path                                | Purpose                   |
| ------ | ----------------------------------- | ------------------------- |
| `GET`  | `/backup/import/sync/agents`        | List remote agents        |
| `POST` | `/backup/import/sync/preview`       | Single-agent sync preview |
| `POST` | `/backup/import/sync/preview/batch` | Multi-agent sync preview  |
| `POST` | `/backup/import/sync`               | Execute single-agent sync |
| `POST` | `/backup/import/sync/batch`         | Execute multi-agent sync  |

## Component Reference

| Class                     | Type           | Responsibility                                                                                                |
| ------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
| `IResourceSource`         | Interface      | Transport abstraction — reads agent config from any source                                                    |
| `ZipResourceSource`       | Implementation | Reads from unzipped directory, implements `AutoCloseable`                                                     |
| `RemoteApiResourceSource` | Implementation | Reads from a remote EDDI's REST API through `OutboundHttp`, every document scrubbed, size- and request-capped |
| `StructuralMatcher`       | CDI Bean       | Matches source/target resources, produces `ImportPreview`                                                     |
| `UpgradeExecutor`         | CDI Bean       | Writes source content into target resources (version increments)                                              |
| `ImportPreview`           | Record         | Preview with resource diffs (CREATE/UPDATE/SKIP/CONFLICT/REMOVE) and `warnings`                               |
| `ExportPreview`           | Record         | Resource tree with selectability flags                                                                        |
| `SyncMapping`             | Record         | Source→target agent pair for batch sync                                                                       |
| `SyncRequest`             | Record         | Full sync request with selections and workflow order                                                          |
