Agents

Agents are the workers in Maestro. Each agent is an LLM with a specific role, personality, and set of tools.

What is an Agent?

An agent combines:

• System prompt: Instructions that define what the agent does
• Model configuration: Which LLM to use and how
• Tools: Capabilities the agent can use
• Description: Used by the orchestrator for routing decisions

Built-in Agents

Orchestrator

Routes requests to specialized agents based on intent analysis.

Personal Assistant

General conversation, questions, planning, and everyday tasks.

Coder

Programming tasks using Claude Code for file operations and commands.

Static vs Dynamic Agents

Static Agents

Defined in YAML files under config/. Changes require a restart.

config/personal-assistant.yaml

name: personal-assistant
description: General-purpose assistant for everyday tasks

model:
  provider: anthropic
  name: claude-sonnet-4-20250514
  temperature: 0.7
  max_tokens: 4096

system_prompt: |
  You are a helpful personal assistant...

tools:
  - calculator
  - datetime

Dynamic Agents

Created through conversation. No restart required.

You: Create an agent called research-assistant that helps with research
Maestro: Created research-assistant. What system prompt should it use?

You: It should search for information, summarize findings, and cite sources
Maestro: Updated. What tools should it have?

You: Give it calculator and datetime
Maestro: Done. research-assistant is now available.

Dynamic agents are stored in SQLite and persist across restarts.

Agent Configuration

Field	Required	Description
name	Yes	Unique identifier
description	Yes	What the agent does (for routing)
model.provider	Yes	LLM provider (anthropic)
model.name	Yes	Model ID
model.temperature	No	Randomness (0-1)
model.max_tokens	No	Max response tokens
system_prompt	Yes	Agent instructions
tools	No	Enabled tool names

How Routing Works

The orchestrator sees agent descriptions and decides routing:

Agents available:
- personal-assistant: "General-purpose assistant for everyday tasks"
- coder: "Programming and code execution via Claude Code"
- research-assistant: "Research topics and summarize findings"

User message: "Help me debug this Python error"
Orchestrator decision: Route to "coder"

Tip

Write clear, specific descriptions. The orchestrator uses these to make routing decisions, so vague descriptions lead to poor routing.

Managing Dynamic Agents

Use these tools to manage agents at runtime:

Create

You: Create an agent called writer that helps with content

Or be explicit:

You: Use create_agent to make an agent called writer with description
"Helps write blog posts, emails, and documentation"

Update

You: Update writer's system prompt to focus on technical writing
You: Add the calculator tool to writer

List and Inspect

You: List all agents
You: Show me the writer agent's configuration

Delete

You: Delete the writer agent

Best Practices

1. Specific descriptions: Help the orchestrator route correctly
2. Focused system prompts: Don’t try to make agents do everything
3. Minimal tools: Only enable tools the agent needs
4. Test routing: Verify requests go to the right agent

Agent Lifecycle

1. Creation: YAML file loaded or dynamic agent created
2. Registration: Added to the agent registry
3. Discovery: Orchestrator can see it for routing
4. Execution: Handles requests routed to it
5. Persistence: Conversations stored in memory