Validation

How validation works and what gets checked.

What Gets Validated

The SDK validates your agent definition before export to ensure it’s ready for the platform.

Schema Validation:

Required fields are present
Naming conventions are correct
Version format is valid (semantic versioning)
References are defined

Structural Validation:

Workflows have at least one node
Entry nodes exist
Node references point to valid resources
All dependencies are defined

Using validate()

from ainalyn import AgentBuilder, validate
 
agent = (
    AgentBuilder("MyAgent")
    .version("1.0.0")
    .description("My first agent")
    .add_workflow(workflow)
    .build()
)
 
# Validate
result = validate(agent)
 
if result.is_valid:
    print("Validation passed!")
else:
    print("Validation failed:")
    for error in result.errors:
        print(f"  {error.code}: {error.message}")

Validation Results

The ValidationResult object contains:

Properties:

is_valid - Boolean indicating if validation passed
errors - List of validation errors
warnings - List of warnings (optional issues)

Error Details: Each error contains:

code - Error code (e.g., “MISSING_AGENT_VERSION”)
path - Location in the definition (e.g., “agent.version”)
message - Human-readable description
severity - ERROR or WARNING

Naming Rules

Valid names:

"my-agent"           # Lowercase with hyphens
"data-processor-v2"  # Letters, numbers, hyphens
"fetch-data"         # Starts with letter

Invalid names:

"MyAgent"      # Must be lowercase
"my_agent"     # No underscores
"my agent"     # No spaces
"2-agent"      # Must start with letter

Version Format

Valid versions:

"1.0.0"        # Semantic versioning
"2.1.3"        # Major.minor.patch
"0.1.0"        # Pre-release

Invalid versions:

"1.0"          # Must have three parts
"v1.0.0"       # No 'v' prefix
"1.0.0-beta"   # No pre-release tags (yet)

Common Validation Errors

MISSING_AGENT_VERSION

Cause: Forgot to set agent version.

# Error
agent = AgentBuilder("my-agent").build()
 
# Fix
agent = AgentBuilder("my-agent").version("1.0.0").build()

INVALID_WORKFLOW_NAME

Cause: Workflow name doesn’t follow naming rules.

# Error
workflow = WorkflowBuilder("MyWorkflow").build()
 
# Fix
workflow = WorkflowBuilder("my-workflow").build()

MISSING_WORKFLOWS

Cause: Agent has no workflows.

# Error
agent = AgentBuilder("my-agent").version("1.0.0").build()
 
# Fix
agent = (
    AgentBuilder("my-agent")
    .version("1.0.0")
    .add_workflow(workflow)
    .build()
)

UNDEFINED_RESOURCE_REFERENCE

Cause: Node references a resource that doesn’t exist.

# Error - prompt not defined
node = (
    NodeBuilder("task")
    .description("Task node")
    .uses_prompt("analyzer")  # No prompt named "analyzer"
    .build()
)
 
# Fix - define the prompt first
prompt = PromptBuilder("analyzer").template("Analyze: {data}").build()
 
agent = (
    AgentBuilder("my-agent")
    .version("1.0.0")
    .add_prompt(prompt)  # Add prompt to agent
    .add_workflow(workflow)
    .build()
)

INVALID_ENTRY_NODE

Cause: Workflow entry_node doesn’t exist in nodes.

# Error
workflow = (
    WorkflowBuilder("process")
    .entry_node("start")  # No node named "start"
    .add_node(NodeBuilder("step1").goal("Do something").build())
    .build()
)
 
# Fix
workflow = (
    WorkflowBuilder("process")
    .entry_node("step1")  # Valid node name
    .add_node(NodeBuilder("step1").goal("Do something").build())
    .build()
)

Best Practices

1. Validate early and often

# Build progressively, validate at each step
node = NodeBuilder("task").goal("Process data").build()
workflow = WorkflowBuilder("main").add_node(node).build()
agent = AgentBuilder("my-agent").version("1.0.0").add_workflow(workflow).build()
 
# Validate before export
result = validate(agent)
if not result.is_valid:
    print("Fix these errors before exporting:")
    for error in result.errors:
        print(f"  - {error.message}")

2. Check validation results

result = validate(agent)
 
# Don't ignore validation!
if not result.is_valid:
    raise ValueError(f"Invalid agent: {result.errors[0].message}")
 
# Now safe to export
yaml_output = export_yaml(agent)

3. Use compile_agent() for safety

from ainalyn.api import compile_agent
from pathlib import Path
 
# Automatically validates before exporting
result = compile_agent(agent, Path("agent.yaml"))
 
if result.is_successful:
    print(f"Compiled to {result.output_path}")
else:
    print("Compilation failed:")
    for error in result.validation_result.errors:
        print(f"  {error.message}")

When Validation Happens

Builder validation:

Happens during .build() call
Checks required fields
Validates value formats
Throws exceptions immediately

Schema validation:

Happens when you call validate()
Checks structural correctness
Returns ValidationResult
Does not throw exceptions

Example:

# Builder validation - throws exception
try:
    agent = AgentBuilder("Invalid Name!").build()  # Throws exception
except InvalidValueError as e:
    print(f"Builder error: {e.message}")
 
# Schema validation - returns result
agent = AgentBuilder("my-agent").version("1.0.0").build()
result = validate(agent)  # Returns ValidationResult
 
if not result.is_valid:
    print(f"Schema error: {result.errors[0].message}")