Define agents with models, roles, tools, permissions, and behavioral configuration

Agents

The agent block defines a single AI agent in your topology. Each agent has a model, an optional role, and a set of capabilities and constraints.

Basic Syntax

agent researcher {
  model: sonnet
  role: "Finds relevant information and summarizes findings"
  tools: [Read, Grep, WebSearch]
}

Field Reference

Field	Type	Required	Description
`model`	identifier	Yes	The model to use (e.g. `sonnet`, `opus`, `gpt-4o`)
`role`	string	No	Description of what this agent does
`permissions`	identifier	No	One of `supervised`, `autonomous`, `interactive`, `unrestricted`
`prompt`	string or block	No	System prompt — inline string or multi-line block
`phase`	identifier	No	Assigns agent to a named phase
`tools`	list	No	Tools this agent can use
`disallowed-tools`	list	No	Tools explicitly denied
`reads`	list	No	Data sources this agent can read from
`writes`	list	No	Data destinations this agent can write to
`outputs`	list or block	No	Structured outputs this agent produces
`skip`	condition	No	Condition under which to skip this agent
`retry`	number	No	Number of retry attempts on failure
`isolation`	boolean	No	Whether to run in an isolated context
`invocation`	identifier	No	`auto` (default) or `manual`
`behavior`	identifier	No	`blocking` (default) or `advisory`
`memory`	list	No	Memory domains this agent accesses
`skills`	list	No	Skills available to this agent
`mcp-servers`	list	No	MCP servers this agent connects to
`background`	boolean	No	Whether agent runs in the background

Permissions

Level	Description
`supervised`	Agent actions require approval
`autonomous`	Agent acts freely within its tool set
`interactive`	Agent can prompt the user for input
`unrestricted`	No constraints on agent behavior

agent deployer {
  model: opus
  permissions: supervised
  tools: [Bash, Write]
}

Prompt Blocks

Short prompts use an inline string. Longer prompts use a prompt block:

agent writer {
  model: sonnet
  prompt {
    "You are a technical writer."
    "Always use active voice."
    "Keep paragraphs under 3 sentences."
  }
}

Tools

List tools by name. Use the mcp.server.* wildcard to grant all tools from an MCP server:

agent analyst {
  model: sonnet
  tools: [Read, Grep, mcp.postgres.*]
  disallowed-tools: [Bash]
}

Outputs

Define what structured data an agent produces:

agent classifier {
  model: sonnet
  outputs: [category, confidence]
}

Or use a block for richer output definitions:

agent classifier {
  model: sonnet
  outputs {
    category: "The document category"
    confidence: "0.0 to 1.0 confidence score"
  }
}

Skip Conditions

Skip an agent based on a prior agent's output:

agent formatter {
  model: sonnet
  skip: reviewer.verdict == "approved"
}

Tips

Every topology needs at least one agent.
The model field is the only required field.
Use disallowed-tools to deny specific tools while granting broad access via wildcards.
invocation: manual means the agent only runs when explicitly triggered (e.g. by a slash command or another agent).

Agents

On this page