validate()

import { validate } from "agentopology";

Validates a parsed TopologyAST against 82 semantic rules. Returns a ValidationResult with any errors found.

Signature

function validate(ast: TopologyAST): ValidationResult

Parameters

Returns

interface ValidationResult {
  valid: boolean;
  errors: Array<{
    rule: string;
    message: string;
    location?: string;
  }>;
}

• valid -- true if no errors were found
• errors -- Array of validation errors, each with a rule name, message, and optional location in the source

Usage

The standard pattern is to parse first, then validate:

import { parse, validate } from "agentopology";
import { readFileSync } from "fs";

const source = readFileSync("my-topology.at", "utf-8");
const ast = parse(source);
const result = validate(ast);

if (result.valid) {
  console.log("Topology is valid");
} else {
  for (const error of result.errors) {
    console.error(`[${error.rule}] ${error.message}`);
  }
}

Example output

For a topology with issues, validation returns descriptive errors:

const result = validate(ast);
// result.errors:
// [
//   { rule: "agent-defined", message: "Flow references agent 'editor' which is not defined", location: "flow:4" },
//   { rule: "no-orphan-agents", message: "Agent 'logger' has no incoming or outgoing flow edges", location: "agent:logger" }
// ]

Validation rules

The validator checks 82 rules covering structure, flow, and pattern conformance. Some of the key rules:

• agent-defined -- Every agent referenced in flow must be defined
• no-orphan-agents -- Every agent must participate in the flow
• phase-required -- Pipeline patterns require phase numbers on agents
• max-guard -- Conditional loops must have max guards to prevent infinite loops
• output-defined -- Flow conditions referencing outputs must match declared output fields
• model-required -- Every agent must specify a model
• flow-reachable -- All agents must be reachable from the intake node

What's next

• Scaffold a validated topology to a platform
• Visualize the topology as an interactive graph
• Learn about all available bindings