feat: Add Structured I/O (Input/Output Schemas) similar to Agno

[gouravjshah]

Overview

Add structured input/output schema support to AOF, similar to Agno's Pydantic-based approach. This will enable:

• Type-safe, validated agent outputs
• Consistent output formatting across different LLM runs
• Runtime schema specification (flexible per-execution)
• Better integration with downstream systems

Motivation

Currently, LLM outputs are non-deterministic and vary in format:

Run 1: Raw docker output table
Run 2: Bullet list with container names
Run 3: Bullet list with status info

This makes it hard to:

• Parse outputs programmatically
• Build reliable automations
• Present consistent UI/UX

Design

Core Components

1. OutputSchema - JSON Schema for response validation
2. InputSchema - JSON Schema for input validation
3. Common schemas - Pre-built schemas for docker, kubectl, etc.
4. CLI integration - --output-schema flag for runtime specification
5. Smart rendering - Format hints (table, list, json) for display

API Design (Rust)

use aof_core::schema::{OutputSchema, schemas};

// Use pre-built schema
let schema = schemas::container_list();

// Or define custom schema
let schema = OutputSchema::from_json_schema(json!({
    "type": "object",
    "properties": {
        "containers": {"type": "array", ...}
    }
}));

// Execute with schema
runtime.execute_with_schema("agent-name", "input", Some(schema)).await?;

CLI Usage

# Use pre-built schema
aofctl run agent docker-health.yaml --output-schema container-list

# Use custom schema from file
aofctl run agent docker-health.yaml --output-schema-file ./schemas/custom.json

# Inline schema
aofctl run agent docker-health.yaml --output-schema '{"type":"object",...}'

Implementation Plan

• Create aof-core/src/schema.rs with core types
• Export schema module from aof-core
• Add output_schema field to AgentContext
• Update agent executor to use structured output with LLM
• Add CLI flags for schema specification
• Implement schema-based rendering
• Write internal docs
• Write user-facing docs with examples
• Comprehensive tests

References

• Agno output schema: https://docs.agno.com/basics/input-output/agent/usage/output-schema-on-run
• Agno structured input: https://docs.agno.com/basics/input-output/agent/usage/structured-input
• JSON Schema: https://json-schema.org/

Benefits

✅ Consistent outputs across runs
✅ Type-safe validation
✅ Better UX (formatted tables, lists)
✅ Programmatic output parsing
✅ Works across all tools (docker, kubectl, any command)
✅ Runtime flexibility (different schemas per execution)