Your First Agent

In this tutorial, you'll create a custom agent that summarizes text. You'll learn how agents are structured, how to write system prompts, and how to use your agent.

What is an Agent?

An agent is an AI assistant with a specific purpose. Each agent is defined as a directory containing two files:

config.json — Settings like model, tools, and skills
system.md — Instructions that define the agent's behavior

Agents are stored in ~/.config/ayo/agents/. Each agent directory is prefixed with @.

Create the Agent

Use the agents create command to create a new agent:

ayo agents create @summarizer

This creates:

                ~/.config/ayo/agents/@summarizer/
├── config.json
└── system.md
            

Write the System Prompt

Open the system prompt file in your editor:

$EDITOR ~/.config/ayo/agents/@summarizer/system.md

Replace the contents with:

                # Summarizer Agent

You are a summarization specialist. Your job is to distill text into clear, concise summaries.

## Guidelines

- Preserve key facts and main arguments
- Use bullet points for multiple items
- Keep summaries to 3-5 sentences unless asked otherwise
- Maintain the original tone (formal, casual, technical)
- Never add information not present in the original

## Output Format

For short texts: A single paragraph summary.
For long texts: A brief overview followed by key points as bullets.
            

Configure the Agent

Open the config file:

$EDITOR ~/.config/ayo/agents/@summarizer/config.json

The default config works well, but you can customize it:

                {
  "model": "claude-sonnet-4-20250514",
  "tools": [],
  "skills": []
}
            

Use Your Agent

Now use your agent with the @ prefix:

                ayo @summarizer "The quarterly report shows revenue increased 15% year-over-year, 
driven primarily by expansion into Asian markets. Customer acquisition costs 
decreased by 8% while retention rates improved to 94%. The company expects 
continued growth in Q2, though supply chain challenges may impact margins."
            

Output:

                Revenue grew 15% YoY, primarily from Asian market expansion. Customer 
acquisition costs fell 8% and retention reached 94%. Q2 growth is expected 
but supply chain issues may affect margins.
            

Pipe Content to Your Agent

You can pipe content from files or other commands:

                # Summarize a file
cat meeting-notes.txt | ayo @summarizer "Summarize this"

# Summarize email thread
cat customer-inquiry.eml | ayo @summarizer "Summarize the key points"

# Summarize a report
cat quarterly-report.pdf | ayo @summarizer "What are the main findings?"
            

List Your Agents

See all available agents:

ayo agents list

View Agent Details

See an agent's configuration and system prompt:

ayo agents show @summarizer

Best Practices

Single purpose — Each agent should do one thing well
Clear instructions — Be specific about expected behavior
Output format — Define how responses should be structured
Version control — Keep your agents in git for backup and sharing

Next Steps

Skills — Add reusable capabilities to agents
Tickets — Coordinate work between multiple agents
Agents Reference — Full configuration options