Agents Reference

Agents are defined as directories containing configuration and behavior instructions.

Directory Structure

                @myagent/
├── config.json     # Configuration
└── system.md       # Behavior instructions
            

config.json Schema

                {
  "model": "claude-sonnet-4-20250514",
  "tools": ["bash", "memory", "delegate"],
  "skills": ["customer-service"],
  "trust": "standard"
}
            

Fields

Field	Type	Default	Description
`model`	string	(global default)	LLM model to use
`tools`	string[]	`[]`	Enabled tools
`skills`	string[]	`[]`	Attached skills
`trust`	string	`"standard"`	Trust level for sandbox

Tools

Available tools to enable for agents:

Tool	Description
`bash`	Execute shell commands in sandbox
`memory`	Store and retrieve persistent facts
`delegate`	Delegate tasks to other agents
`ticket`	Create and manage tickets
`file`	Read and write files in workspace

Trust Levels

Level	Description
`minimal`	No filesystem or network access
`standard`	Workspace access only (default)
`elevated`	Additional bind mounts, network access

system.md Format

The system prompt defines agent behavior. Use markdown for structure.

Recommended Structure

                # Agent Name

Brief description of the agent's purpose.

## Role

Detailed explanation of what this agent does.

## Guidelines

- Guideline 1
- Guideline 2
- Guideline 3

## Output Format

Description of expected output format.

## Examples

Example inputs and outputs if helpful.

Example: Email Triager

                # Email Triage Agent

You categorize and prioritize incoming emails.

## Categories

- **urgent**: Requires immediate response
- **important**: Respond within 24 hours
- **routine**: Respond when convenient
- **spam**: Ignore or delete

## Output Format

For each email, output JSON:

```json
{
  "category": "urgent|important|routine|spam",
  "priority": 1-5,
  "summary": "Brief summary",
  "suggested_action": "What to do"
}
```

## Guidelines

- Default to lower priority when uncertain
- Flag anything mentioning legal or security
- Preserve original sender intent in summaries
            

Example Configurations

Minimal Agent

                // config.json
{
  "model": "claude-sonnet-4-20250514"
}
            

Agent with Tools

                // config.json
{
  "model": "claude-sonnet-4-20250514",
  "tools": ["bash", "file"],
  "trust": "standard"
}
            

Agent with Skills

                // config.json
{
  "model": "claude-sonnet-4-20250514",
  "skills": ["customer-service", "email-etiquette"]
}
            

Full Configuration

                // config.json
{
  "model": "claude-opus-4-20250514",
  "tools": ["bash", "memory", "delegate", "file"],
  "skills": ["research", "analysis"],
  "trust": "elevated"
}
            

Agent Location

Agents are searched in this order:

~/.config/ayo/agents/@name/ — User agents
~/.local/share/ayo/agents/@name/ — Built-in agents

User agents override built-in agents with the same name.