Importing agents

If you already have an agent defined somewhere else, a Claude Code agent .md, an internal system’s export, or a definition your pipeline generates, you don’t rebuild it by hand. xpander imports it: one call creates (or updates) the agent, deploys it with a workspace, seeds its files, wires its schedules, and returns a report that accounts for every piece of the source definition. Every way in lands on the same import engine:

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

The conversational flow

From any surface where you talk to Omni, Xpander Chat or an MCP client connected through Omni in your MCP client, simply hand over the definition:

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

In Claude Code you can go the other way too. With Claude Code connected to Omni’s MCP endpoint, ask it to “export this agent to xpander” and it passes the definition across for you. Omni parses the definition, runs the import, and relays the full report, including every tools entry in the source that has no xpander skill equivalent, named one by one, with a suggested next step for each.

The direct flow: `import_agent_manifest`

When the agent arrives as structured data rather than a Claude .md, skip the parsing and pass the canonical manifest object to the import_agent_manifest call (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; the version this deployment understands
`name`	string, required	The agent’s name. Re-importing the same name updates that agent in place, never a duplicate
`description`	string	Short description shown in Xpander Chat
`instructions`	string	The agent’s prompt; becomes its general instructions
`model`	string	Informational only: the source model is never force-mapped. The agent starts on your org default, and the report says so
`files`	list of `{path, content}`	Text files seeded into the agent’s workspace (paths relative to the workspace 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 the agent needs. Names only; values are refused as parameters and captured through a secure browser link instead
`mcp_servers`	list of `{name, url?, command?, transport}`	Each entry has exactly one of `url` (a remote MCP endpoint, attached as a skill) or `command` (a local stdio process, consent-gated, see below)
`tools`	list of string	Source `tools` entries (Claude Code built-ins such as `Bash` or `Read`). Mapped by name to skills: workspace-covered entries carry over automatically, everything else is reported with a suggested equivalent
`destructive_ops`	list of `{name, script}`	Scripts seeded under `ops/` in the workspace and reported as needing an approval gate before real use

Validation is all-or-nothing: a manifest that doesn’t validate imports nothing, and the error names each bad field with how to fix it.

What happens to each asset

Asset	What the import does	Who authenticates	Your action
Instructions / description	Become the agent’s prompt and description	-	none
Model	Not applied; the org default is used and the report says so	-	pick a model in Xpander Chat if you want a specific one
Files	Seeded into the workspace and verified; an unconfirmed write is reported, never counted as success	-	none
Schedules	Crons validated up front, then created and deployed together	-	none
Secrets	Named, never valued: a secure browser link is minted for the user to type the values	you, in the browser	open the link, enter the values
Remote MCP endpoints (`url`)	Attached to the agent as skills, deduplicated by URL on re-import	you, in Xpander Chat, if the endpoint requires OAuth	authenticate when the endpoint asks
Local stdio processes (`command`)	Named, never installed: running a command-line process takes your explicit consent. Importing over MCP raises one consent card naming each command verbatim	you, on the consent card	approve with `confirm_omni_request` (or in Xpander Chat); dismiss and nothing runs
`tools` entries	Mapped by name to skills; every entry with no xpander equivalent is named in the report with a next step	per entry, when you wire a skill later	wire a skill or MCP endpoint per hint
Destructive ops	Seeded as scripts under `ops/`, reported as needing an approval gate before the agent runs them for real	-	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 the values live afterwards, and who may reach them, is on Credentials.

Credential kind	Where it is entered	How
Workspace secrets (env vars)	Browser, by you	The import auto-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-running an import with the same name (as the same user) updates the existing agent in place: instructions and description are rewritten, files re-seeded, and missing schedules and MCP endpoints added (matched by (cron, prompt) and by URL). The report says updated, not created. This makes the manifest safe to keep in version control and re-apply on every change.

The CI flow

A pipeline provisions an agent with the same manifest and no human in the loop:

Call import_agent_manifest with the manifest (over the Omni MCP endpoint, authenticated 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 the same call on every change; the import is idempotent, so the pipeline converges the deployed agent to the manifest.

Local stdio processes stay consent-gated even in CI: the import names them in its report, and a person approves the 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.

Once the agent exists, Agent settings is where you adjust its model, instructions and runtime behavior.

Start here

Build an agent

Channels

Run and monitor

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

​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

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