Importing agents

Bring an agent you already defined elsewhere: a Claude Code agent .md, an internal system’s export, or a definition your pipeline generates. One import call creates or updates it.

Pick a flow

Flow	You bring	Best for
Conversational	The agent’s `.md` (or an export `.zip` link), pasted to Omni	One-off migrations from Claude Code
Direct	The canonical import manifest (JSON) via `import_agent_manifest`	Clients and scripts that hold the agent as structured data
CI	The same manifest, plus the REST secrets endpoint for headless credentials	Pipelines that provision agents automatically

All three use the same import engine.

The conversational flow

Paste the definition to Omni, in xpander Chat or an MCP client connected through Omni in your MCP client.

You:  Import this agent: <paste the Claude agent .md, frontmatter + prompt body>
Omni: Imported 'Report Helper' (created + deployed) ...

Omni runs the import and relays the report, which names every tools entry with no xpander skill equivalent and suggests a next step for each. From Claude Code connected to Omni’s MCP endpoint, you can just ask it to “export this agent to xpander”.

The direct flow: `import_agent_manifest`

For structured data, pass the canonical manifest to import_agent_manifest, available in any Omni conversation, including over MCP.

{
  "schema_version": "1",
  "name": "report-helper",
  "description": "Sends the weekly report",
  "instructions": "You are a report helper...",
  "files": [{ "path": "docs/notes.md", "content": "..." }],
  "schedules": [{ "cron": "0 9 * * 1", "prompt": "Send the weekly report", "title": "Weekly" }],
  "secret_names": ["GITHUB_TOKEN"],
  "mcp_servers": [
    { "name": "github", "url": "https://mcp.github.example/mcp", "transport": "streamable-http" },
    { "name": "local-fs", "command": "npx -y fs-mcp", "transport": "stdio" }
  ],
  "tools": ["Bash", "Read", "WebSearch"],
  "destructive_ops": [{ "name": "purge_stale_rows.sh", "script": "#!/bin/sh\n..." }]
}

The REST API has a separate import for agents published as templates. The Import agent endpoint (POST /v1/agents/template_import/{template_id}) copies a template from your organization, or one shared with it, into a new agent. The manifest import on this page is for definitions that live outside xpander.

Manifest fields

Field	Type	What it carries
`schema_version`	string	Always `"1"` today
`name`	string, required	Re-importing the same name updates that agent in place, never a duplicate
`description`	string	Shown in xpander Chat
`instructions`	string	The agent’s general instructions
`model`	string	A model id from your org’s catalog (bare or `provider/model_id`), or a Claude alias (`sonnet`, `opus`, `haiku`) that resolves to the newest matching Claude model. A value the catalog does not allow is not applied, and the report says so.
`files`	list of `{path, content}`	Text files seeded into the workspace, paths relative to its root, 2 MB total inline
`schedules`	list of `{cron, prompt, title?}`	Recurring runs. `cron` is a 5-field UTC cron, validated before anything is created
`secret_names`	list of string	Env var names only. Values are refused as parameters and captured through a secure browser link
`mcp_servers`	list of `{name, url?, command?, transport}`	Exactly one of `url` (a remote endpoint, attached as a skill) or `command` (a local stdio process, consent-gated)
`tools`	list of string	Source entries such as `Bash` or `Read`, mapped by name to skills. Workspace-covered ones carry over. The rest are reported with a suggested equivalent
`destructive_ops`	list of `{name, script}`	Scripts seeded under `ops/`, reported as needing an approval gate before real use

Validation is all-or-nothing. An invalid manifest imports nothing, and the error names each bad field and how to fix it.

What happens to each asset

Asset	What the import does	Your action
Instructions / description	Become the agent’s prompt and description	none
Model	Resolved against the catalog. If it is not there or the catalog cannot be read, a new agent uses the org default and a re-import keeps the current model. The report says which applied	pick a model in xpander Chat if the report says it was not applied
Files	Seeded and verified. An unconfirmed write is reported, never counted as success	none
Schedules	Validated up front, then created and deployed together	none
Secrets	Named, never valued. A secure browser link is minted for you	open the link, enter the values
Remote MCP endpoints (`url`)	Attached as skills, deduplicated by URL on re-import	authenticate in xpander Chat if the endpoint asks for OAuth
Local stdio processes (`command`)	Named, never installed. Importing over MCP raises one consent card naming each command verbatim	approve with `confirm_omni_request` (or in xpander Chat). Dismiss it and nothing runs
`tools` entries	Mapped to skills. Unmatched entries are named with a next step	wire a skill or MCP endpoint per hint
Destructive ops	Seeded under `ops/`, flagged for an approval gate	wrap as a custom function with an approval gate

Credentials: where each kind is entered

Secret values never travel through the import, the conversation or the report. Where they live afterwards: Credentials.

Credential kind	Where it is entered	How
Workspace secrets (env vars)	Browser, by you	The import mints a secure link (30-minute expiry). Values go straight to the vault
Workspace secrets, headless (CI)	API call with an org key	`POST /v1/agents/{agent_id}/workspace/secrets`
Remote MCP OAuth	Browser, by you	xpander Chat’s MCP connect flow on the attached endpoint
Local stdio processes	Consent card, by you	Approve the exact command. Nothing runs until you do

Idempotent re-import

Re-importing the same name, as the same user, updates the agent and the report says updated. Instructions and description are rewritten, model is set again when it resolves, files are re-seeded, and missing schedules and MCP endpoints are added (matched by (cron, prompt) and by URL). The manifest is safe to keep in version control and re-apply on every change.

The CI flow

Import the manifest

Call import_agent_manifest over the Omni MCP endpoint with an org API key. The report returns the agent_id.

Set credentials headlessly

POST /v1/agents/{agent_id}/workspace/secrets with your org API key writes the same vault the browser link does.

Re-run on every change

The import is idempotent, so the pipeline converges the agent to the manifest.

Local stdio processes stay consent-gated even in CI. A person approves each command once, on the card.

The import is non-blocking on anything it cannot map. The agent deploys anyway, and the report names every tools entry, endpoint and credential that still needs you. Nothing is dropped silently.

Start here

Build an agent

Company Brain

Channels

Run and monitor

xpander Desktop

Pick a flow

The conversational flow

The direct flow: `import_agent_manifest`

Manifest fields

What happens to each asset

Credentials: where each kind is entered

Idempotent re-import

The CI flow

Next steps

Adjust the imported agent

Enter the agent's credentials

​Pick a flow

​The conversational flow

​The direct flow: import_agent_manifest

​Manifest fields

​What happens to each asset

​Credentials: where each kind is entered

​Idempotent re-import

​The CI flow

​Next steps

Adjust the imported agent

Enter the agent's credentials

Pick a flow

The conversational flow

The direct flow: `import_agent_manifest`

Manifest fields

What happens to each asset

Credentials: where each kind is entered

Idempotent re-import

The CI flow

Next steps