Export & Import Agents

Export bundles an agent and its dependencies into a portable .zip, and import recreates it in another tenant or environment. Use it to promote an agent from staging to production, clone a template across clients, or back up a configuration.

---

What's in a bundle

A bundle is a .zip containing manifest.json (version, source tenant/agency, source data-residency region), agent.json (the full agent config), and kb/ (knowledge-base document blobs). Optional addons are selected at export time:

Addon	Contents
Tools	Tool definitions + their integration bindings
DataFiles	Embedded agent data files
KnowledgeBase	KB documents (blobs) + embedding metadata
ParameterDefinitions / ParameterGroups	Collected-parameter config
WidgetEmbed / WidgetDemoPage	Widget allow-list + demo-page settings
Goals / Hooks / Metadata	Agent goals, lifecycle hooks, metadata
ChannelConfigurations	Channel shells referenced by the agent's enabled channels
SsrfAllowlist	SSRF allowlist entries for the agent's webhook-tool hosts

---

Secrets are never exported

Bundles are safe to move between environments because all credentials are stripped:

• Integration secrets (API keys, OAuth client/refresh/access tokens, basic-auth, custom header values) — imported integrations are created without credentials.
• Channel credentials (Twilio auth tokens, SIP/email passwords, WhatsApp/Slack/Telegram tokens) are tenant-scoped — channel configs import as shells (numbers/SIDs/hosts kept, secrets blank).
• Webhook signing secret — never carried; a fresh secret is generated on import and returned once in the result.

Knowledge-base vectors are not carried either — documents are re-indexed on the target tenant with its embedding model.

---

Exporting

# Preview what's available
GET /api/v1/agents/{id}/export/preview
 
# Download the bundle (all addons, or a comma-separated subset)
GET /api/v1/agents/{id}/export?addons=Tools,KnowledgeBase,ChannelConfigurations

---

Importing

Import is two steps — preview the bundle, then commit:

POST /api/v1/agents/import/preview      # multipart: file=<bundle.zip>  → { uploadId, preview }
POST /api/v1/agents/import/{uploadId}/commit
  { "addons": ["Tools","KnowledgeBase"], "overrideExistingTools": false,
    "overrideExistingIntegrations": false, "renameTo": null }

The imported agent is always created inactive so you can finish configuration before it goes live.

---

Post-import readiness report

The commit result includes a structured readiness report plus free-text warnings. In the console it renders as a panel after import; via the API it's the readiness array and requiresConfiguration flag. It surfaces everything you must do before activating:

Kind	Action
Integration	Add credentials for each integration created without secrets
Channel	Reconfigure provider tokens/numbers for each recreated channel
Webhook	Update your receiver with the new signing secret (webhookSecret, shown once)
KnowledgeBase	Documents are queued for re-indexing — semantic search is unavailable until it finishes
DataResidency	The source region differs from this tenant's — verify compliance

The result also reports channelConfigurationsImported, ssrfAllowlistEntriesImported, and knowledgeBaseDocumentsQueuedForIndexing.

Region note. Provider endpoints resolve at runtime from the target tenant's data-residency region. A cross-region import silently changes where conversations and recordings are processed — the readiness report flags this when the regions differ.

---

Bundle versions

The current bundle version is 3 (adds agent flags, KB embedding metadata, channel/SSRF addons, and the source region). Older v1/v2 bundles still import.