TypeDialog/crates/typedialog-agent/README.md

typedialog-agent

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

Part of the 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
```text

## 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
```text

### 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(())
}
```text

## 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
```text

### 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
```text

## Project Structure

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

## 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