Agents

An agent combines a model, persona, tools, skills, and memory settings in one configuration file. Create separate agents for tasks that need different models or permissions.

For example, keep a coding agent for repository changes, a researcher for web investigation, and a reviewer with fewer permissions for unattended work.

Create and use an agent

jazz agent create
jazz agent chat <agent-name>

The wizard lets you choose its model, persona, name, and tools. Ask it for a task, such as:

Read the current changes, identify bugs, and suggest fixes. Do not modify files yet.

Use jazz agent edit <agent-name> to change its settings. Changes take effect on the next turn. See Creating agents for the walkthrough.

What an agent is made of

• Identity: its name and description.
• Model: the provider and model that handle reasoning and tool use.
• Persona: reusable instructions for its behavior and voice.
• Tools: the actions it can request, including explicit denials.
• Skills: procedures it can load when needed.
• Companions: optional specialist models for images, audio, and video.
• Memory and context settings: what it remembers and how much history it carries.

Example agent file:

{
  "id": "reviewer",
  "name": "Reviewer",
  "config": {
    "persona": "coder",
    "llm": {
      "provider": "openai",
      "model": "gpt-5.4"
    }
  }
}

jazz agent create writes one interactively. Files live under the active Jazz data directory and are shared by every surface using that installation, so the same agent answers in your terminal, in CI, and on Telegram.

Model

Written provider/model with a slash: openrouter/z-ai/glm-5.3-flash, mistral/mistral-large-latest, ollama/qwen3. Stored split into llm.provider and llm.model. Local providers are also supported; see Model providers.

Persona

Shapes how the agent communicates (tone, style, vocabulary) independently of the model. Ships with default, coder, and researcher, and you can write your own. See Personas.

Tools

• tools is additive. It grants capabilities on top of the built-in bundle the persona already permits. Listing a built-in tool changes nothing, and leaving one out does not withhold it.
• deniedTools subtracts, last. It is applied after every other grant, which makes it the reliable way to enforce a per-agent ceiling. An agent with execute_command denied cannot run shell commands, whatever the approval policy says.

Use deniedTools to remove capabilities the job does not need. See Tools.

Context budget

llm.maxContextTokens caps how much conversation this agent may carry, in tokens, whatever the model would allow. Unset, it uses the model’s own window. Set it to keep cost and latency predictable, or to stop a model degrading long before its advertised limit: the agent warns at 70% of the budget and auto-compacts at 80%, so a smaller ceiling means earlier, cheaper compaction rather than a hard failure. See Context management.

Skills

Skills are not bundles of tools. They are playbooks: Markdown instructions the agent loads on demand when a task matches. Two agents can have identical tools and differ entirely in which skills they reach for. See Skills.

Companions

companions lets one identity borrow specialist models without switching its main model. Analysis and generation bind independently, per medium:

{
  "companions": {
    "analyze:image": "provider/vision-model",
    "analyze:audio": "provider/audio-model",
    "generate:image": "provider/image-generation-model"
  }
}

A companion run is bounded, tool-free, and isolated: analysis returns evidence, generation returns a file, and neither creates a second identity or conversation. A cheap text model can orchestrate the work while a vision model does the looking. See Model companions.

Project instructions (AGENTS.md)

Jazz reads AGENTS.md, the standard file for project instructions. Add your build commands, test commands, and coding conventions at the repository root. Every Jazz agent working there reads it automatically.

Discovery runs on each turn against the agent’s current working directory:

The walk climbs from the working directory to the repository root, the nearest ancestor with a .git, and stops there, so a checkout never inherits an unrelated AGENTS.md from a directory above it. Files enter the system prompt outermost-first, so when two conflict, the more specific one wins. Each file is capped at 32 KB; keep them short and they stay effective.

Edits take effect on the next turn. Nothing to restart.

Agent configurations

Delegation

Use subagents for independent work that can happen in parallel, such as reviewing separate packages or researching different approaches. Ask the parent agent to divide the work:

Have subagents review the API, database, and frontend changes separately.
Combine their findings, verify each issue, and report the fixes we need.

The parent needs spawn_subagent in its toolset. You see child activity while it works; the parent collects their results into one answer.

spawn_subagent hands a task to a child run on this same installation, with a task, a persona (coder, researcher, or default), and its own context window. It returns an agentId at once and the child works while the parent keeps going; the parent collects the child’s answer with wait_subagents, and gets back a summary and the cost, not the child’s transcript.

Each child’s whole answer is saved with the conversation’s working state. wait_subagents returns each answer once, and when several long answers would not fit together it returns a preview of each, sharing the space between them, with the id to read the whole answer by with retrieve_tool_result.

Each child has its own context window. Use resultSchema, a JSON Schema with root type object, to require a validated structured result.

A child runs on its parent’s model unless the parent names another with model. The model must come from the parent’s own provider and be able to call tools, so a parent on Claude Opus can hand mechanical work to Claude Haiku but cannot send a child to another provider. A model the provider does not list is refused, and the refusal names the ones it does.

To run the same brief over many inputs, the parent calls map_subagents once with a task and up to 100 inputs. Each input becomes one child, and {{input}} in the task marks where it goes. Every child shares the persona, model, limits and resultSchema. Children past maxLiveSubagents wait as queued and start as earlier ones finish, so one wait_subagents call collects every answer, in input order.

While children work, the parent can manage them:

An agent granted spawn_subagent gets these six with it. Guidance and pauses take effect before the child’s next model call, and a paused child spends nothing. Cancelling stops it at once, with the tools and processes it started. A child that finishes is announced to the parent on its next step, and guidance a child finished too early to read is reported back as undeliveredMessages.

Children can share findings without going through the parent. The parent and every child in its tree read and write one blackboard: a child posts what a sibling could use (a located file, a ruled-out lead, a sourced fact) and checks the board before starting work another child may have done. In chat the board lasts for the conversation; elsewhere for the run. It keeps the latest 500 posts. A post written after its author read external content is marked untrusted, and so is the read that returns it.

Delegation limits:

• A child never holds more tools than its parent. The parent’s effective toolset becomes the child’s allowlist, so delegation cannot widen reach.
• Depth stops at 3. A subagent can spawn one, but the chain ends there. maxSubagentDepth: 0 disables delegation outright.
• At most 10 at once by default (maxLiveSubagents), each with 30 iterations by default, against the parent’s 100. In chat the count spans turns: a child still working from an earlier turn holds a slot.
• Cost rolls up and is shared. Each child’s spend is added to the parent’s as it happens, so children running together stop at the parent’s maxCostUSD instead of each spending the whole remainder. An unpriced child marks the total cost as unknown. A chat child that finishes after its parent’s turn ended is recorded in the spend ledger under that turn’s run.
• In chat, children work in the background. The parent can answer while its children are still going: the turn ends, you keep chatting, and when a child finishes the parent gets a new turn to read its result and tell you what came of it. A message you send while the parent is waiting on its children with wait_subagents ends that wait, so the parent reads you first. Children belong to the conversation: /new, switching conversations or leaving the chat stops the ones still working. In fullscreen, select a running child in the list under the composer and press x to stop it; anywhere, ask the parent to cancel it.
• Elsewhere, children never outlive the run. In jazz run, a workflow, a bot, or a goal’s cycle, nobody is there to hand the parent another turn, so if it answers while children are still going, Jazz cancels the paused ones, waits for the rest, and gives the parent one more step to read their results. Work that should continue after the run is a goal. A run that parks or detaches stops its children; a resumed run starts with none.
• Their approvals name them. In chat, a child’s approval prompt starts with its name. In an unattended run, a child’s gated call is declined and the child reports that to the parent.

A subagent is not a peer. A subagent is yours, on your machine, inside your trust boundary. A peer belongs to somebody else and is bounded by a disclosure tier because of it.

Editing agents and managing conversations

Agents are one JSON file each under the Jazz data directory (~/.jazz/agents/<id>.json by default). Edit them with jazz agent edit <id>, or by hand.

Conversations persist separately, per conversation id. In the terminal, /resume browses past ones, /new starts a fresh one, /start aliases it, /create creates an agent, /rename names the current conversation, and /fork continues on a new conversation id while carrying the full history forward and preserving the original branch (resume it later with /resume); headless callers pass --conversation <id> to continue the same thread across invocations. Transcripts are plaintext JSON: treat that directory as sensitive.

Related

• Create an agent: the practical walkthrough
• Agent configuration: every field
• Personas · Skills · Tools
• Starting runs: terminal commands, workflows, schedules, and events