Creating agents

Agents are the core of Jazz. Each agent is a configured AI assistant with its own persona, model, and tool access. You can create specialized agents for different tasks—a coding agent with Git and shell access, a research agent with web search, or a communication agent with email and calendar tools.

Creating your first agent

Start the agent wizard

Run the interactive agent creation command:

jazz agent create

The wizard guides you through each configuration step with ESC-based back navigation.

Select an LLM provider

Choose from supported providers:

Anthropic (Claude models)
OpenAI (GPT models)
Google (Gemini models)
xAI (Grok models)
OpenRouter (access to hundreds of models)
Ollama (local models)
DeepSeek, Mistral, Groq, Cerebras, and more

If you haven’t configured an API key yet, the wizard prompts you to enter one. Keys are saved to ~/.jazz/config.json.

Use OpenRouter’s Free Models Router to get started without a credit card.

Choose a model

Select which model the agent should use:

Which model would you like to use?
❯ claude-4.5-sonnet
  claude-4.5-opus
  claude-3-haiku
  ...

Models are searchable—just start typing to filter.

Reasoning models (like OpenAI’s o1/o3) show an additional “reasoning effort” step where you can set the effort level to low, medium, or high.

Select a persona

Personas define the agent’s behavior and expertise. Built-in options:

default - General-purpose assistant (requires description)
coder - Software development specialist
researcher - Research and analysis expert

Predefined personas (coder, researcher) automatically configure appropriate tool categories.

Name your agent

Provide a unique name:

Name of your new agent: my-coding-assistant

Valid characters: letters, numbers, underscores, hyphens. Maximum 100 characters.

Describe the agent (optional)

If you selected the “default” persona, provide a description:

Describe what this agent will do: Helps with TypeScript development and code reviews

This description helps you identify the agent’s purpose later.

Configure tools

Select which tool categories the agent can access:File Management

Read, write, edit files
Search file contents
Directory operations

Shell Commands

Execute terminal commands
Run scripts
System operations

Git

Status, diff, log
Commit, push, pull
Branch management

HTTP

Make API requests
Fetch web resources

Web Search

Search the web
Research information

MCP Servers (if configured)

Any enabled MCP server tools appear here

If the selected model doesn’t support tools (like some reasoning models), tool selection is skipped.

Agent configuration

Agents are stored in ~/.jazz/agents/ with this structure:

{
  "id": "my-coding-assistant",
  "name": "my-coding-assistant",
  "description": "Helps with TypeScript development",
  "config": {
    "persona": "coder",
    "llmProvider": "anthropic",
    "llmModel": "claude-4.5-sonnet",
    "tools": [
      "read_file",
      "write_file",
      "edit_file",
      "bash",
      "git_status",
      "git_diff",
      "git_commit"
    ]
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Configuration options

Field	Type	Description
`persona`	string	Behavior profile (default, coder, researcher)
`llmProvider`	string	LLM provider name
`llmModel`	string	Specific model ID
`reasoningEffort`	string	For reasoning models: disable, low, medium, high
`tools`	string[]	List of tool names the agent can use

Predefined agent types

Jazz includes two predefined agent configurations:

Coder agent

Optimized for software development:

Tools: File Management, Shell Commands, Git, HTTP, Web Search
Use cases: Code reviews, refactoring, debugging, feature implementation
Example: jazz agent create → select “coder” persona

Researcher agent

Designed for information gathering and analysis:

Tools: Web Search, HTTP, File Management, Shell Commands
Use cases: Market research, technical documentation, competitive analysis
Example: jazz agent create → select “researcher” persona

Managing agents

List all agents

jazz agent list

Shows all configured agents with their models and creation dates.

Chat with an agent

# By name
jazz agent chat my-coding-assistant

# By ID
jazz agent chat abc123

# Interactive selection
jazz

Delete an agent

jazz agent delete my-coding-assistant

Tool categories explained

File Management

Tools for reading, writing, and manipulating files:

read_file - Read file contents
write_file - Create or overwrite files
edit_file - Make targeted edits
glob - Find files by pattern
grep - Search file contents

Source: src/core/agent/tools/register-tools.ts:10-30

Shell Commands

Execute terminal commands:

bash - Run shell commands
execute_command - Execute with timeout and error handling

Shell commands require approval by default. Use with caution.

Git

Version control operations:

git_status - Show working tree status
git_diff - Show changes
git_log - View commit history
git_commit - Commit changes
git_push - Push to remote
git_branch - Branch management

Source: src/core/agent/tools/register-tools.ts:12

HTTP

Make HTTP requests:

http_request - GET, POST, PUT, DELETE requests
Supports headers, query parameters, request bodies
Automatic JSON parsing

Source: src/core/agent/tools/register-tools.ts:13

Web Search

Search the web for information:

Configurable search provider (Tavily, Perplexity, Brave)
Returns ranked results with snippets
Automatic source attribution

Configuration in jazz.config.json:

{
  "web_search": {
    "provider": "tavily",
    "api_key": "your-key"
  }
}

Advanced: Custom tool selection

For fine-grained control, edit the agent JSON file directly:

{
  "config": {
    "tools": [
      "read_file",
      "write_file",
      "git_status",
      "git_diff",
      "http_request"
    ]
  }
}

Restart Jazz to load changes:

jazz agent chat my-agent

Best practices

Start narrow, expand as needed - Begin with minimal tool access and add more as you discover use cases.

Use personas for consistency - Predefined personas ensure agents have appropriate tools for their domain.

Name agents by function - Use descriptive names like code-reviewer, email-assistant, or research-bot.

Review shell command access - Agents with shell access can execute arbitrary commands. Only enable for trusted workflows.

Examples

Code review agent

jazz agent create

Provider: anthropic
Model: claude-4.5-sonnet
Persona: coder
Name: code-reviewer
Tools: File Management, Git (no shell commands)

Research agent with web access

jazz agent create

Provider: openrouter
Model: anthropic/claude-4.5-sonnet
Persona: researcher
Name: web-researcher
Tools: Web Search, HTTP, File Management

Email automation agent

jazz agent create

Provider: openai
Model: gpt-4
Persona: default
Description: Manages email triage and responses
Tools: Email (via MCP), File Management

Email tools require MCP server configuration. See the MCP integration guide.

Next steps

Using skills - Extend agents with packaged expertise
MCP integration - Connect to external services
Workflows - Automate agents with scheduled tasks

Get Started

Core Concepts

Guides

Use Cases

Creating agents

Creating your first agent

Agent configuration

Configuration options

Predefined agent types

Coder agent

Researcher agent

Managing agents

List all agents

Chat with an agent

Delete an agent

Tool categories explained

Advanced: Custom tool selection

Best practices

Examples

Code review agent

Research agent with web access

Email automation agent

Next steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Use Cases

Documentation Index

​Creating your first agent

​Agent configuration

​Configuration options

​Predefined agent types

​Coder agent

​Researcher agent

​Managing agents

​List all agents

​Chat with an agent

​Delete an agent

​Tool categories explained

​Advanced: Custom tool selection

​Best practices

​Examples

​Code review agent

​Research agent with web access

​Email automation agent

​Next steps

Build docs developers (and LLMs) love

Creating your first agent

Agent configuration

Configuration options

Predefined agent types

Coder agent

Researcher agent

Managing agents

List all agents

Chat with an agent

Delete an agent

Tool categories explained

Advanced: Custom tool selection

Best practices

Examples

Code review agent

Research agent with web access

Email automation agent

Next steps