Schemas

The schemas block defines typed data structures that agents use to exchange structured information. Schemas ensure that agent outputs conform to a known shape, making inter-agent communication reliable and predictable.

Basic Syntax

schemas {
  review-result {
    verdict: string
    issues: list
    confidence: number
    approved: boolean
  }
}

Supported Types

Type	Description	Example
`string`	Text value	`"approved"`
`number`	Numeric value (integer or float)	`0.95`
`boolean`	True or false	`true`
`list`	Ordered collection	`["issue1", "issue2"]`
`object`	Nested structure	`{ name: "test" }`

Defining Schemas

Each schema has a name and a set of typed fields:

schemas {
  analysis-report {
    summary: string
    risk-level: string
    findings: list
    score: number
    needs-review: boolean
  }

  deployment-plan {
    target: string
    services: list
    rollback-steps: list
    estimated-downtime: number
  }
}

Using Schemas with Agents

Reference schemas in agent outputs to enforce structured output:

topology code-review : [pipeline] {
  schemas {
    review-result {
      verdict: string
      issues: list
      suggested-fixes: list
      confidence: number
    }
  }

  agent reviewer {
    model: opus
    tools: [Read, Grep]
    outputs: review-result
  }

  agent fixer {
    model: sonnet
    tools: [Read, Write]
    # Can reference reviewer.issues, reviewer.suggested-fixes, etc.
  }

  flow {
    reviewer -> fixer  [when reviewer.verdict == "needs-fixes"]
  }
}

Schema References in Flow Conditions

Schema fields are accessible in flow conditions using dot notation:

flow {
  analyst -> writer       [when analyst.risk-level == "low"]
  analyst -> senior-writer [when analyst.risk-level == "high"]
}

Nested Schemas

Use object type for nested structures:

schemas {
  test-report {
    summary: string
    results: object
    passed: boolean
    total-tests: number
    failures: list
  }
}

Full Example

topology analysis-pipeline : [pipeline, fan-out] {
  schemas {
    security-scan {
      vulnerabilities: list
      severity: string
      safe: boolean
    }

    performance-report {
      metrics: list
      bottlenecks: list
      score: number
    }
  }

  agent code-scanner {
    model: sonnet
    outputs: security-scan
    tools: [Read, Grep]
  }

  agent perf-analyzer {
    model: sonnet
    outputs: performance-report
    tools: [Read, Bash]
  }

  agent report-writer {
    model: opus
    tools: [Write]
  }

  flow {
    [code-scanner, perf-analyzer] -> report-writer
  }
}

Tips

Schemas make flow conditions type-safe. A condition like analyst.score > 80 only works if score is defined as number in the schema.
Use schemas whenever agents need to pass structured data to downstream agents.
Schema field names follow the same lowercase-with-hyphens convention as identifiers.
List types are untyped — the items can be any value. Use descriptive field names to clarify expected contents.

Schemas

On this page