# typedialog-agent

> Type-safe AI agent execution with 3-layer validation pipeline

Part of the [TypeDialog](https://github.com/yourusername/typedialog) ecosystem.

## Features

- **3-Layer Pipeline**: MDX → Nickel → MD with validation at each step
- **Type Safety**: Compile-time type checking via Nickel
- **Multi-Format**: .agent.mdx, .agent.ncl, .agent.md support
- **CLI + Server**: Execute locally or via HTTP API
- **Cache Layer**: Memory + disk caching for fast re-execution
- **Integration**: Works with typedialog-ai for form-based agent creation

## Architecture

```
Layer 1: Markup Parser
  .agent.mdx → AST
  Parse @directives, {{variables}}, markdown

Layer 2: Nickel Transpiler + Evaluator
  AST → Nickel code → Type check → AgentDefinition

Layer 3: Executor
  AgentDefinition + Inputs → LLM → Validated Output
```

## Quick Start

### CLI Usage

```bash
# Execute agent
typeagent architect.agent.mdx --input feature_name="authentication"

# Transpile to Nickel (inspect generated code)
typeagent transpile architect.agent.mdx -o architect.agent.ncl

# Validate without execution
typeagent validate architect.agent.mdx

# Start HTTP server
typeagent serve --port 8765
```

### Programmatic Usage

```rust
use typedialog_ag_core::{AgentLoader, AgentFormat};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let loader = AgentLoader::new();

    // Load agent
    let agent = loader.load(Path::new("architect.agent.mdx")).await?;

    // Execute with inputs
    let inputs = [("feature_name", "auth")].into_iter()
        .map(|(k, v)| (k.to_string(), serde_json::Value::String(v.to_string())))
        .collect();

    let result = loader.execute(&agent, inputs).await?;

    println!("{}", result.output);
    Ok(())
}
```

## Integration with TypeDialog Ecosystem

### With typedialog-ai

```bash
# 1. Create agent using AI-assisted form
typedialog form agent-builder.toml --backend ai
# → Generates architect.agent.mdx

# 2. Execute with typeagent
typeagent architect.agent.mdx
```

### With Vapora (MCP Plugin)

```rust
// Vapora uses typedialog-ag-core as library
use typedialog_ag_core::AgentLoader;

let loader = AgentLoader::new();
let agent = loader.load(Path::new("agents/architect.agent.mdx")).await?;
// Execute via Vapora orchestration
```

## Project Structure

```
typedialog-agent/
├── typedialog-ag-core/      # Core library (reusable)
├── typedialog-ag/       # CLI binary
└── typedialog-ag-server/    # HTTP server
```

## Documentation

- [Implementation Plan](../../.coder/2025-12-23-typedialog-agent-implementation.plan.md)
- [Markup Syntax](./docs/MARKUP_SYNTAX.md)
- [Nickel Integration](./docs/nickel.md)
- [HTTP API](./docs/API.md)

## License

MIT