Skip to main content
Agents are defined by AGENT.md files — a Markdown document with YAML frontmatter that tells Octo what the agent does and what tools it needs.

​
Interactive Wizard

The fastest way to create an agent: 
/create-agent
The wizard guides you through:
1

Name and description

Validated format with collision detection against existing agents.
2

Agent type

Standard (tools + prompt) or Deep research (persistent workspace with planning middleware).
3

Tool selection

Numbered table of all available tools (built-in + MCP). Shortcuts: builtin, all, none.
4

Purpose description

Free-text description of what the agent should do.
5

AI generation

An LLM generates a full system prompt based on your description, selected tools, and examples from existing agents. The AGENT.md is previewed before saving.
Agents are immediately available after the graph rebuilds.

​
Manual Creation

Create .octo/agents/<name>/AGENT.md: 
---
name: my-analyst
description: Analyzes data files and produces reports
type: ""
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

You are a data analyst. When given a dataset or file path:

1. Read and understand the data structure
2. Identify patterns, anomalies, and key metrics
3. Produce a clear summary with findings

Always show your work — include the commands you ran and their output.

​
Frontmatter Fields

FieldRequiredDescription
nameYesAgent identifier (lowercase, hyphens ok)
descriptionYesOne-line description shown in /agents and used by supervisor for routing
typeNo"" for standard, "deep_research" for deep agents
toolsNoList of built-in tool names. Omit to get all built-in tools

​
Deep Research Agents

Set type: deep_research for agents that need:
  • Persistent workspace — files at .octo/workspace/<date>/
  • Planning middleware — TodoList for tracking multi-step work
  • Summarization middleware — automatic context compression
  • Sub-agent spawning — delegate subtasks
Deep agents are built with the deepagents library and get their own middleware stack automatically.

​
Agent Loading

At startup, Octo loads agents from:
  1. AGENT_DIRS — external project directories (colon-separated in .env)
  2. .octo/agents/ — Octo-native agents
List all loaded agents with /agents.

​
Tips

Write clear, specific descriptions — the supervisor uses them to decide which agent handles each request. Vague descriptions lead to poor routing.
The system prompt (everything below the frontmatter) supports full Markdown. Use headers, lists, and code blocks to structure your agent’s instructions.