Skip to content

Export and import agents

Every agent's configuration can be downloaded as a single readable definition file, in YAML or JSON, and applied back to any agent. Applying it to the same agent restores a backup or reviews changes in source control. Applying it to a second agent in your account clones a setup. Applying it to an agent in a different account moves or shares an agent.

Export writes everything you configure under Behavior and Capabilities to a file. Import applies that file to an existing agent section by section, leaving anything the file does not mention untouched.

This document covers the console workflow, what the file carries, and the CLI and API equivalents.

Export an agent

Open the agent and go to Settings · Export & import. Choose Download YAML, which reads top to bottom in the same order as the console's Behavior and Capabilities pages, or Download JSON.

The document is two-layered, matching how the agent is organized:

  • Header: the agent's name, description, template lineage, and model settings.
  • definition: the authored document in reading order, covering identity, personality, guardrails, goals, playbooks, and message templates. Each piece keeps its template lineage, so catalog updates keep working after an import.
  • capabilities: capability configuration, covering scheduling and its representatives, people fields and the update permission, knowledge such as Things and collections, outreach settings, and custom integration contracts.

What the file never contains

The export is deliberately limited to the portable definition. It never includes credentials, account-specific links, or conversation data:

Not exported Why After importing
Channel bindings Channels are provisioned per account Set up channels on the new agent
Credentials An integration's auth header and a notification API key are write-only Re-enter them on the new agent
Connections A linked Google or Slack account belongs to the source business Connect the account once, then point the capability at it
Knowledge Sources Uploaded files live in your account's knowledge base Re-upload Sources (or re-run website import)
People, conversations, appointments Customer data rather than agent configuration Nothing to do

Because there are no secrets inside, a definition file is safe to keep in source control or hand to another team.

Import a definition

On the target agent, open Settings · Export & import, choose the file, review the list of sections it will overwrite, and confirm.

Import applies the file as a patch:

  • Only the sections present in the file are written. A file whose definition layer contains just guardrails changes nothing else.
  • A section present with an empty value clears that section on the agent.
  • Server-owned fields in the file (id, framework, secrets, timestamps) are ignored and reported as skipped.
  • Validation matches the console's own rules. Playbooks, for example, must include exactly one default.
  • Files exported before August 2026 use a retired flat layout and are rejected with a message asking for a re-export.

After the import the console shows exactly which sections were applied and which were skipped.

Imports overwrite

Importing replaces each section it touches wholesale rather than merging item by item. Before experimenting, download a backup export of the target agent. Re-importing that file restores what you had.

Move an agent to another account

  1. Export the agent as YAML from the source account.
  2. Switch to the target account, or send the file to its operator, and create a new agent there. A blank one is fine.
  3. On the new agent, open Settings · Export & import and import the file.
  4. Reconnect what the file does not carry: channels, credentials, OAuth connections, and Knowledge Sources.

The new agent gets its own id, webhook credentials, and channel addresses. Nothing references the source account.

From the CLI

The anychat CLI wraps the same endpoints:

# Download a definition
anychat agents export agent-acme-a1b2c3 --output acme.yaml

# Apply a definition to an existing agent
anychat agents import agent-other-d4e5f6 --input acme.yaml

# Create a brand-new agent from a definition in one step
anychat agents create --name "Acme (staging)" --input acme.yaml

Point the CLI at a different account's API key to import across accounts.

From the API

Two endpoints under the Agent API:

# Export (YAML by default; ?format=json for JSON)
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.anychat.ai/v1/orgs/$ORG/agents/$AGENT/export"

# Import (send the parsed document as JSON)
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @acme.json \
  "https://api.anychat.ai/v1/orgs/$ORG/agents/$AGENT/import"

Export needs the agents:read scope, which the viewer role carries. Import needs agents:write, which the editor role carries.

What's next