Write, validate, scaffold, and visualize your first AgenTopology file in under five minutes

Quickstart

This guide walks you through the core workflow: write a .at file, validate it, scaffold it to a platform, and visualize the agent graph.

1. Write a topology

Create a file called content-pipeline.at:

topology simple-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
    }
  }
}

2. Validate

Check that your topology is well-formed:

agentopology validate content-pipeline.at

If everything is correct you'll see:

content-pipeline.at is valid.
  topology: simple-pipeline
  patterns: pipeline, human-gate
  agents: 3 (researcher, writer, reviewer)
  flow edges: 6

Validation catches issues like missing agent definitions, unreachable nodes, and invalid flow conditions before you deploy anything.

3. Scaffold

Generate platform-specific config files from your topology:

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

This creates the directory structure, CLAUDE.md files, and agent prompts that Claude Code expects. You can swap --target for other platforms:

agentopology scaffold content-pipeline.at --target codex
agentopology scaffold content-pipeline.at --target cursor

4. Visualize

See your agent graph as an interactive diagram:

agentopology visualize content-pipeline.at

This opens a browser window showing your agents, flow edges, and conditional routing. You can also generate a static image:

agentopology visualize content-pipeline.at --format png --output graph.png

What's next

That's the full loop: write, validate, scaffold, visualize. For a deeper walkthrough of building a topology from scratch, continue to Your First Topology.

Quickstart

Quickstart

1. Write a topology

2. Validate

3. Scaffold

4. Visualize

What's next

On this page