115 lines
2.7 KiB
Markdown
115 lines
2.7 KiB
Markdown
|
# 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
|