Syncing Data

Syncing allows enterprise customers to promote configurations from one tenant to another. This enables standard deployment workflows where you develop in Dev environment and promote to Staging or Production.

Use Case

Create separate tenants for each environment:

Develop and test agents in acme-dev, then sync to acme-staging for QA, then sync to acme-prod for release.

Syncable Resources

The following resources can be synced between tenants:

Syncing from the UI

1. Mark resources as syncable — Enable the Syncable toggle on any agent or tool you want to promote
2. Open the Sync panel — Navigate to Settings → Sync in your tenant
3. Select the target tenant — Choose the environment to sync to (e.g., acme-staging)
4. Run sync — Click Sync to promote all syncable resources

When you sync an agent, all its dependencies are automatically included:

• Tools attached to the agent
• Knowledge bases attached to the agent
• Connections used by those tools
• Sub-agents (for supervisor agents)

ID Mapping

When a resource is synced, a new deterministic ID is generated based on the source tenant, target tenant, and original ID. This ensures:

• Consistent IDs across syncs (re-syncing updates rather than duplicates)
• References between resources are preserved (e.g., agent → tool relationships)
• Source and target resources remain distinct

Sync Direction

Syncing is one-way only. Changes flow from source tenant to target tenant. The target tenant receives a copy marked with syncedFrom indicating the source tenant.

Resources with syncedFrom set are excluded from further syncs to prevent circular chains.

Sync API

For CI/CD pipelines or automation, syncing is also available via API.

Get Available Steps

GET /api/tenant/sync/steps

Returns the ordered list of sync steps.

Sync a Specific Step

POST /api/tenant/sync/:targetTenantId/:step

Syncs a single resource type from the authenticated user's tenant to the target tenant.

Parameters:

• targetTenantId — The tenant to sync to
• step — One of: documents, connections, knowledgeBases, tools, workflows, agents, evaluations

Example:

# Sync tools from current tenant to staging
curl -X POST https://api.example.com/api/tenant/sync/acme-staging/tools \
  -H "Authorization: Bearer $TOKEN"

# Then sync agents (which reference those tools)
curl -X POST https://api.example.com/api/tenant/sync/acme-staging/agents \
  -H "Authorization: Bearer $TOKEN"

Full Environment Promotion

To promote all syncable resources, call each step in order:

for step in documents connections knowledgeBases tools workflows agents evaluations; do
  curl -X POST "https://api.example.com/api/tenant/sync/acme-prod/$step" \
    -H "Authorization: Bearer $TOKEN"
done

Permissions

• Only Admin or Owner roles can initiate syncs
• The user must have access to both source and target tenants
• Synced resources preserve the original creator metadata

Behavior Notes

Upsert Semantics

Syncing performs an upsert:

• If the resource doesn't exist in the target tenant, it's created
• If it already exists (same sync ID), it's updated with the latest values

Credentials and Secrets

Connections include encrypted credentials. When synced:

• Credentials are re-encrypted for the target tenant
• Template expressions (e.g., ${vars.API_KEY}) are preserved
• You may need to configure environment variables in the target tenant

Versioning

For versioned resources (agents, tools):

• Both draft (version 0) and published versions are synced
• Version numbers are preserved
• The target tenant receives the same version history

Built-in Tools

Built-in tools (those without a tenant ID) are not synced. References to built-in tools are preserved as-is since they're available in all tenants.