Creating Agents

This guide shows you how to create custom agents, either through configuration files or dynamically via conversation.

Decide: Static or Dynamic?

Static (YAML)	Dynamic (Conversation)
Requires restart to change	No restart needed
Version controlled	Stored in SQLite
Good for core agents	Good for experiments
Team-visible in repo	User-created at runtime

Creating a Static Agent

1. Create the YAML file

   Create a new file in config/:

   config/research-assistant.yaml

   name: research-assistant
   description: Helps research topics, summarize findings, and cite sources
   
   model:
     provider: anthropic
     name: claude-sonnet-4-20250514
     temperature: 0.5
     max_tokens: 4096
   
   system_prompt: |
     You are a research assistant. When asked about a topic:
     1. Break down the question into sub-questions
     2. Research each aspect thoroughly
     3. Synthesize findings into a clear summary
     4. Always cite your reasoning
   
     Be thorough but concise. Prefer accuracy over speed.
   
   tools:
     - calculator
     - datetime

2. Restart Maestro

   The new agent will be loaded on startup:

   docker compose restart
   # or
   npm run cli

3. Verify it’s available

   You: List all agents
   Maestro: Available agents:
   - orchestrator
   - personal-assistant
   - coder
   - research-assistant  <-- Your new agent

4. Test routing

   You: Help me research the history of containerization
   [Orchestrator routes to research-assistant]

Creating a Dynamic Agent

Dynamic agents are created through conversation:

1. Create the agent

   You: Create an agent called email-writer
   Maestro: Created email-writer. What should its description be?

2. Set the description

   You: It helps write professional emails and responses
   Maestro: Updated description. What system prompt should it use?

3. Define the system prompt

   You: It should write clear, professional emails. Keep them concise.
   Match the tone to the context - formal for business, friendly for
   colleagues. Always suggest a subject line.
   Maestro: Updated system prompt. What tools should it have?

4. Add tools (optional)

   You: Just datetime so it can reference the current date
   Maestro: Added datetime. email-writer is ready to use.

5. Test it

   You: Help me write an email declining a meeting politely
   [Orchestrator routes to email-writer]

Agent Design Tips

Write Good Descriptions

The orchestrator uses descriptions for routing. Be specific:

# Bad - too vague
description: Helps with stuff

# Good - specific use case
description: Writes and reviews Python code, runs tests, and debugs errors

Craft Effective System Prompts

system_prompt: |
  You are a code reviewer specializing in Python.

  When reviewing code:
  1. Check for bugs and logic errors
  2. Identify security vulnerabilities
  3. Suggest performance improvements
  4. Note style inconsistencies

  Be direct. Don't pad feedback with unnecessary praise.
  Prioritize issues by severity: critical > important > minor.

Tip

Start specific and loosen up. It’s easier to broaden an agent’s scope than to narrow it down.

Choose Tools Wisely

Only enable tools the agent needs:

Agent Type	Recommended Tools
General assistant	calculator, datetime
Coder	claude_code, list_projects, switch_project
Agent manager	create_agent, update_agent, list_agents
Research	calculator, datetime

Updating Agents

Static Agents

Edit the YAML file and restart:

# Edit config/research-assistant.yaml
docker compose restart

Dynamic Agents

Update through conversation:

You: Update email-writer's temperature to 0.3
Maestro: Updated email-writer temperature to 0.3.

You: Add calculator to email-writer
Maestro: Added calculator to email-writer.

You: Change email-writer's system prompt to focus on technical emails
Maestro: Updated email-writer system prompt.

Deleting Agents

Static Agents

Delete the YAML file and restart.

Dynamic Agents

You: Delete the email-writer agent
Maestro: Deleted email-writer.

Caution

Deleting an agent doesn’t delete conversation history. Previous messages from that agent remain in memory.

Example: Content Pipeline

Create a set of agents that work together:

You: Create an agent called outline-writer that creates content outlines

You: Its prompt should be: "You create detailed outlines for blog posts
and articles. Ask clarifying questions about the target audience and goal.
Structure outlines with clear sections and bullet points."

You: Create an agent called draft-writer that writes first drafts

You: Its prompt should be: "You write first drafts based on outlines.
Write in a clear, engaging style. Use the outline structure but expand
each point into full paragraphs."

You: Create an agent called editor that reviews and improves drafts

You: Its prompt should be: "You edit content for clarity, flow, and
engagement. Suggest specific improvements. Fix grammar and style issues.
Preserve the author's voice."

Now the orchestrator can route content requests to the appropriate stage.