Your First Topology

This tutorial walks you through building a complete content pipeline topology, one block at a time. By the end you'll have a working .at file with agents, conditional flow routing, and a trigger.

Start with the topology declaration

Every .at file begins with a topology declaration. This names your topology and declares which patterns it uses:

topology content-pipeline : [pipeline, human-gate] {

}

• content-pipeline is the name. Use kebab-case.
• : [pipeline, human-gate] declares the patterns this topology implements. Patterns give the validator rules to check against.

Add the meta block

The meta block holds version and description metadata:

topology content-pipeline : [pipeline, human-gate] {
  meta {
    version: "1.0.0"
    description: "Research, write, and review — a minimal content pipeline"
  }
}

The version field follows semver. The description is used in generated documentation and the visualizer.

Add an orchestrator

The orchestrator coordinates the overall flow. It handles entry and exit points:

orchestrator {
  model: sonnet
  generates: "commands/create.md"
  handles: [intake, done]
}

• model sets which LLM the orchestrator uses.
• generates is the file the orchestrator produces for bootstrapping.
• handles lists the named flow endpoints this orchestrator manages.

Add agents

Now define the agents that do the actual work. Each agent has a role, a model, a phase number, and the tools it can use.

The researcher

agent researcher {
  role: researcher
  model: sonnet
  phase: 1
  tools: [Read, Grep, Glob, WebSearch]
  writes: ["workspace/research.md"]
}

• phase: 1 means this agent runs first in the pipeline.
• tools lists the MCP tools the agent is allowed to call.
• writes declares which files this agent produces.

The writer

agent writer {
  role: writer
  model: sonnet
  phase: 2
  tools: [Read, Write, Glob]
  reads: ["workspace/research.md"]
  writes: ["workspace/draft.md"]
  outputs: { confidence: high | medium | low }
}

• reads declares file dependencies. The writer needs the researcher's output.
• outputs defines structured output fields. Other agents and flow conditions can reference these.

The reviewer

agent reviewer {
  role: reviewer
  model: opus
  phase: 3
  tools: [Read, Grep, Glob]
  reads: ["workspace/draft.md", "workspace/research.md"]
  outputs: { verdict: approve | revise | reject }
}

The reviewer reads both the draft and the original research, then produces a verdict. This verdict drives the conditional routing in the flow.

Define the flow

The flow block describes how agents connect and under what conditions:

flow {
  intake -> researcher
  researcher -> writer
  writer -> reviewer
  reviewer -> writer     [when reviewer.verdict == revise, max 2]
  reviewer -> researcher [when reviewer.verdict == reject, max 1]
  reviewer -> done       [when reviewer.verdict == approve]
}

Reading flow edges

Each line is an edge: source -> target. Optional conditions go in brackets:

• when reviewer.verdict == revise -- this edge only fires when the reviewer's verdict output equals revise.
• max 2 -- this edge can fire at most 2 times, preventing infinite loops.

The flow above creates a feedback loop: the reviewer can send work back to the writer (up to twice) or all the way back to the researcher (once). When the verdict is approve, the flow ends at the done endpoint.

Add triggers

Triggers define how users invoke the topology:

triggers {
  command create {
    pattern: "/create <TOPIC>"
    argument: TOPIC
  }
}

This registers a /create command. When a user types /create AI safety, the TOPIC argument is set to "AI safety" and passed into the flow.

The complete file

Here is the full topology:

topology content-pipeline : [pipeline, human-gate] {
  meta {
    version: "1.0.0"
    description: "Research, write, and review — a minimal content pipeline"
  }

  orchestrator {
    model: sonnet
    generates: "commands/create.md"
    handles: [intake, done]
  }

  agent researcher {
    role: researcher
    model: sonnet
    phase: 1
    tools: [Read, Grep, Glob, WebSearch]
    writes: ["workspace/research.md"]
  }

  agent writer {
    role: writer
    model: sonnet
    phase: 2
    tools: [Read, Write, Glob]
    reads: ["workspace/research.md"]
    writes: ["workspace/draft.md"]
    outputs: { confidence: high | medium | low }
  }

  agent reviewer {
    role: reviewer
    model: opus
    phase: 3
    tools: [Read, Grep, Glob]
    reads: ["workspace/draft.md", "workspace/research.md"]
    outputs: { verdict: approve | revise | reject }
  }

  flow {
    intake -> researcher
    researcher -> writer
    writer -> reviewer
    reviewer -> writer     [when reviewer.verdict == revise, max 2]
    reviewer -> researcher [when reviewer.verdict == reject, max 1]
    reviewer -> done       [when reviewer.verdict == approve]
  }

  triggers {
    command create {
      pattern: "/create <TOPIC>"
      argument: TOPIC
    }
  }
}

Validate and scaffold

Run validation to check for errors:

agentopology validate content-pipeline.at

Then scaffold to your target platform:

agentopology scaffold content-pipeline.at --target claude-code

Inspect the generated files. You'll find agent-specific CLAUDE.md files with role prompts, tool restrictions, and file access rules -- all derived from your single .at file.

What's next

• Explore the Language Reference to learn every block and field available
• Browse Patterns to see what pipeline, supervisor, fan-out, and other patterns offer
• Check out more Examples for real-world topologies