Skip to main content
An agent is a saved setup: instructions, a harness and model, skills, budgets and who may use it. It does no work by itself. Work happens in conversations, and each message you send is one turn. Each conversation is recorded as a task. Runs from Slack, Teams, email, schedules, webhooks or the API are conversations too.

​
What happens when a conversation starts

  1. xpander picks the harness: the one the message names, else the conversation’s last one, else the agent’s default. A new agent’s default follows the organization’s default model: Anthropic (directly or through Amazon Bedrock) gives Claude Code, OpenAI gives Codex, anything else gives OpenCode.
  2. An executor takes the turn. Turns in one conversation run one at a time. Conversations of the same agent run in parallel.
  3. The turn runs in an isolated sandbox. It can’t see other agents’ files or processes. The agent’s directory is at /agent/data, and the conversation works in sessions/<conversation id>.
  4. The harness reaches its model through xpander, with a short-lived token. It never gets a provider key. xpander applies the model policy and budget and records the call.
  5. xpander writes the instructions and connects the skills, then streams the turn into the conversation. Actions that need sign-off appear as approval cards.

​
Instructions and memory

Each turn’s prompt combines the agent’s instructions, its skills, its notes, the person’s memories and the task context, up to 256 KiB. When it is too long, task context and skill descriptions are trimmed first, never the instructions or the output contract. Claude Code reads it through --append-system-prompt-file. Codex and OpenCode read it as AGENTS.md. The agent keeps long-term notes in CLAUDE.md and AGENTS.md at the top of its directory. Tell it to remember something and it writes there.

​
How skills reach the session

  • API connectors and custom actions are served over MCP as mcp__xpander__<action>. xpander attaches the credential, applies approvals and records each call. The session never holds the credential.
  • Remote MCP connectors use the same endpoint. Local MCP connectors are added to the harness’s own configuration.
  • Markdown skills sync into .claude/skills (Claude Code) or ~/.agents/skills (Codex and OpenCode). The agent’s own skills live in local_skills/.
  • Workspace secrets arrive as environment variables, refreshed before every turn.

​
What is isolated, what is shared

Each conversation has its own working directory, harness session and sandbox. All conversations of an agent share its installed packages, skills, notes and the shared/ folder. Two agents never share a directory.
Agent workspace panel at All files listing the output, sessions, shared and skills folders and the AGENTS.md and CLAUDE.md files, beside a conversation

The agent's directory in the Computer view: sessions/ (one folder per conversation), shared/ and skills/ next to the agent's own AGENTS.md and CLAUDE.md. output/ is a folder this agent made for itself; xpander does not create it. Shown with sample data.

​
When a session ends

A turn ends when the harness finishes, after 15 minutes with no output, or after two hours. Your next message resumes the session. A spent budget stops the run with “Execution stopped: budget exceeded.” Closing the tab does not stop a turn. Stop ends what the agent is doing now and keeps the session open.
Stop this turn? dialog: This stops what the agent is doing right now. The session stays open for your next message. Cancel and Stop buttons

Confirming Stop on a running turn.

The sandbox is discarded after each turn. Files stay, and a conversation’s working directory is removed after 14 days idle. Messages, actions and results stay in the record.

​
Next steps

Create and customize an agent

Instructions, harness, model and skills.

Work with tasks and files

The task record and results.

Decide who can use an agent

Permissions on agents and conversations.