Multi-Agent Workflows

Define teams of collaborating agents with agent-compose.yaml

When to use it

Use multi-agent workflows when:

A task requires different areas of expertise (research, writing, editing)
You want to separate concerns into focused, testable agents
A pipeline has distinct stages where output from one agent feeds into another
You need human-in-the-loop checkpoints between steps

If a single agent with the right tools can handle the job, keep it simple. Reach for composition when you genuinely need specialization.

What is agent-compose.yaml

agent-compose.yaml is a companion to agent.yaml. While agent.yaml defines a single agent, agent-compose.yaml defines a team: which agents participate, what roles they play, and how work flows between them.

# yaml-language-server: $schema=https://automagent.dev/schema/v1.json
apiVersion: v1
kind: team

name: content-pipeline
version: 0.1.0
description: A three-agent team that researches, writes, and edits content

The kind: team field distinguishes this from a single-agent definition.

Basic example: Content team

Here is a complete agent-compose.yaml for a content production pipeline with three agents:

apiVersion: v1
kind: team

name: content-pipeline
version: 0.1.0
description: Researches topics, writes drafts, and edits them into polished articles

agents:
  - name: researcher
    description: Finds and synthesizes information on a given topic
    model: claude-sonnet-4-20250514
    instructions: |
      You are a research specialist. Given a topic, find relevant
      information, key facts, and supporting data. Organize your
      findings into a structured research brief with sections for
      key points, statistics, and source references.
    tools:
      - name: web-search
        description: Search the web for current information
      - name: read-url
        description: Read and extract content from a URL
    role: research
    handoff:
      to: writer
      condition: research-complete
      pass:
        - research_brief

  - name: writer
    description: Produces draft articles from research briefs
    model: claude-sonnet-4-20250514
    instructions: |
      You are a technical writer. Given a research brief, write
      a clear, engaging article. Use short paragraphs, headers,
      and concrete examples. Target a developer audience.
    role: drafting
    handoff:
      to: editor
      condition: draft-complete
      pass:
        - draft_article

  - name: editor
    description: Reviews and polishes draft articles
    model: claude-sonnet-4-20250514
    instructions: |
      You are a senior editor. Review the draft for:
      - Factual accuracy against the research brief
      - Clarity and readability
      - Grammar and style consistency
      - Logical flow and structure

      Make direct edits rather than leaving comments.
      Output the final polished article.
    role: editing
    handoff:
      to: output
      condition: editing-complete
      pass:
        - final_article

routing:
  entry: researcher
  type: sequential

Understanding the structure

Agents

Each entry in the agents array is a full agent definition (same fields as agent.yaml) plus two team-specific fields:

role — The function this agent serves in the team. Used for routing and logging.
handoff — Where work goes when this agent is done.

Handoffs

The handoff object controls how work flows between agents:

handoff:
  to: writer           # Name of the next agent
  condition: research-complete  # When to hand off
  pass:
    - research_brief   # Data to pass to the next agent

to — The name of the agent that receives the work next. Use output to indicate the pipeline is done.
condition — A label for the handoff condition. This is used for logging and, in the future, for conditional routing.
pass — A list of named data items to forward to the next agent.

Routing

The routing block defines the overall flow:

routing:
  entry: researcher    # Which agent starts
  type: sequential     # Flow type

The type field indicates the flow pattern:

Type	Description
`sequential`	Agents run in a fixed order, one after another
`parallel`	Multiple agents run simultaneously (results merged)
`conditional`	Routing depends on agent output (branching logic)
`loop`	Agents can cycle back for iterative refinement

Another example: Code review team

apiVersion: v1
kind: team

name: code-review-team
version: 0.1.0
description: Multi-perspective code review with security and performance specialists

agents:
  - name: security-reviewer
    description: Focuses on security vulnerabilities and credential exposure
    model: claude-sonnet-4-20250514
    instructions: |
      Review the code for security issues: injection vulnerabilities,
      credential exposure, insecure dependencies, and access control
      problems. Rate each finding as critical, high, medium, or low.
    role: security
    tools:
      - name: read-file
        description: Read source files
      - name: check-dependencies
        description: Check for known vulnerabilities in dependencies

  - name: performance-reviewer
    description: Identifies performance bottlenecks and optimization opportunities
    model: claude-sonnet-4-20250514
    instructions: |
      Review the code for performance issues: unnecessary allocations,
      O(n^2) algorithms, missing caching opportunities, and database
      query patterns. Suggest specific optimizations.
    role: performance
    tools:
      - name: read-file
        description: Read source files

  - name: summarizer
    description: Combines review findings into a single actionable report
    model: claude-sonnet-4-20250514
    instructions: |
      Combine the security and performance reviews into a single
      report. Prioritize findings by severity. Remove duplicates.
      Format as a markdown checklist that the author can work through.
    role: summary

routing:
  entry:
    - security-reviewer
    - performance-reviewer
  type: parallel
  merge: summarizer

In this example, the security and performance reviewers run in parallel. Their outputs are merged by the summarizer agent.

Shared context

Agents in a team can share context files. Define them at the team level:

context:
  - file: ./CONVENTIONS.md
  - file: ./docs/style-guide.md

Every agent in the team receives these context files in addition to any context defined on the individual agent.

Current status

The agent-compose.yaml schema is defined and validated by the CLI. You can write compose files today and validate them with automagent validate.

The compose runtime — the piece that actually orchestrates multi-agent execution — is planned for a future release. Today, you can:

Define team structures and validate them
Run individual agents from the team with automagent run
Use the schema as documentation for how your agents collaborate

When the runtime ships, your existing compose files will work without changes.