What is an agent?
An agent is a configured Claude CLI instance with a specific role and set of tools. When you run an agent, muxAI spawns aclaude process with the model, system prompt, MCP tools, and environment variables you defined.
Agents are stored in the database and can be run on demand, on a schedule, or as part of a team.
Anatomy of an agent
Every agent has these core properties:| Property | Description |
|---|---|
| Name | Display name (e.g. “News Analyst”) |
| Role | Functional role (e.g. news-analyst, ceo) |
| Model | Claude model to use (Opus, Sonnet, or Haiku) |
| SKILL.md | System prompt that defines the agent’s behavior and expertise |
| Default Prompt | The task given to the agent on each run |
| MCP Mode | Built-in (isolated tool set) or Global (inherits from Claude config) |
| Max Turns | How many think-act cycles the agent gets per run |
Turns
A turn is one cycle of the agent thinking, calling tools, and receiving results. Each tool call and its response counts as one turn. If a tool call fails (wrong argument, network error, etc.), the agent reads the error and retries on the next turn. This self-correction is useful but consumes turns.Creating agents
There are three ways to create an agent:From a template
Pick a pre-built template (News Analyst, Technical Analyst, Data Analyst, or Team Lead) on the New Agent page. Templates pre-fill the role, model, SKILL.md, and MCP settings.
From scratch
Start with a blank agent and configure everything manually. Useful for custom roles outside the built-in templates.
Via team deploy
Use Deploy Team to create a full team (lead + reporters) in one shot from a blueprint. See Teams for details.
Agent lifecycle
An agent moves through these statuses:| Status | Meaning |
|---|---|
| idle | Ready to run |
| running | Currently executing |
| paused | Manually paused, skipped by scheduler |
| error | Last run failed or process died unexpectedly |
| terminated | Soft-deleted, hidden from active views |