Agents as files

Import and export

Your agents’ instructions are yours. You can download any selection of them as a single file, work on it wherever you like, and import it back — and importing is the quickest way to start from one of our ready-made templates.

Both live on the Agents page in the app, and both are available to owners, developers and editors. Viewers can read agents but not import or export them.

What’s in the file

One file holds one or more agents. For each one it carries:

Its instructions — the definition, which is the part you’re usually there to work on.
Its chat presentation — the opening message and the placeholder in the visitor’s message box.
Its name, whether it’s a concierge or a specialist, and an id that identifies it.

It never carries your Claude API key, your embed keys, your conversations, or your organisation’s settings. A file you export is safe to email to a colleague, keep in a backup, or paste into a tool — there are no secrets in it.

Settings stay where they are. Things like your cooldown timer, allowed domains, block duration and fallback messages belong to your organisation rather than to an agent, so they aren’t part of the file and an import never changes them.

Exporting

Open Export on the Agents page and tick the agents you want. Two things make it quicker than it looks:

Tick a concierge and the agents it routes to are ticked too. A concierge is only useful alongside its specialists, so a whole cluster comes out in one go rather than agent by agent.
Select all and Select none for the obvious cases.

You can export any combination you like — one specialist, a whole cluster, several clusters, or everything you own. Nothing in the file assumes the selection makes a coherent whole, so exporting a single agent to work on is perfectly normal.

Editing the file

This is the point of exporting. The file is plain text, so open it in whatever you already use — a text editor, your code editor, or an AI assistant you like working with. Rewriting an agent’s instructions with an AI tool alongside you is far easier in a file than in a browser tab, and having the whole cluster in one place means the tool can see how your agents refer to each other.

Edit the instructions, the opening message and the placeholder freely. Leave the ids alone — they’re how copadre knows which agent is which when the file comes back.

Renaming is a job for the app, not the file. Changing an agent’s name in the file has no effect. Agents refer to each other by a handle worked out from the name, so renaming in the app updates every prompt that mentions that agent in one go — rename there, then export again, and the file you get back is already correct.

Importing

Open Import, choose your file, and it happens in two steps.

First copadre checks the file. If something is wrong it tells you what, and imports nothing at all — it’s all or nothing, so you never end up with half a cluster. If the file is sound you get a summary of exactly what would happen: which agents would be created, which would be updated, which would be left alone, and anything else worth knowing.

Then you confirm. Only at that point is anything written.

Created or updated?

Each agent in the file is matched to one of yours by its id:

A file you exported yourself carries ids, so re-importing it updates those same agents. It doesn’t make copies.
A template from this documentation site has no ids at all, so it always creates new agents. You can import the same template as many times as you like.
An id copadre doesn’t recognise stops the import, with the id shown so you can fix or remove it.

There’s also an import as new agents option, which ignores the ids and creates everything fresh. That’s how you take your own copy of a file a colleague has shared with you, rather than trying to update agents that were never yours.

What an import can never do

This is the part worth knowing before you try it, because it makes importing safe to experiment with:

Nothing is published. Instructions arrive as drafts. Your published agents carry on answering visitors exactly as they were until you publish the new version yourself.
Your existing agents are never switched on or off. An import never changes whether an agent of yours is active. New agents arrive active but with nothing published, so they answer no one until you publish them.
Nothing is deleted. An agent that isn’t in the file is simply left alone. Importing is not a way of syncing, and a partial file means nothing by omission.

So an import can’t change what a visitor sees. Reviewing and publishing each agent is a separate, deliberate act — the same as any other edit.

Limits

A file can be up to 10 MB.
Export appears once you have at least one agent to export.
Owners, developers and editors can import and export. Viewers cannot.

Where next

If you haven’t built anything yet, the fastest start is to import one of the ready-made files: the starter agent for a single assistant, or the starter cluster for a concierge and two specialists that already work together. Once it’s in, fill in your own details, publish, and embed it on your site.