> ## Documentation Index > Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt > Use this file to discover all available pages before exploring further. # Importing agents > Bring an existing agent definition, a Claude Code agent or any structured manifest, into xpander as a deployed agent. 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](/guides/deploy/omni-mcp), simply hand over the definition: ```text theme={"dark"} You: Import this agent: 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): ```json theme={"dark"} { "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](/api-reference/v1/agents/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](/use/agents/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: 1. Call `import_agent_manifest` with the manifest (over the Omni MCP endpoint, authenticated with an org API key). The report returns the `agent_id`. 2. Set credentials headlessly: `POST /v1/agents/{agent_id}/workspace/secrets` with your org API key writes the same vault the browser link does. 3. 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](/use/agents/create) is where you adjust its model, instructions and runtime behavior.