TypeDialog/crates/typedialog-agent/typedialog-ag

TypeAgent CLI

Command-line interface for executing type-safe AI agents defined in MDX format.

Installation

cargo install --path crates/typedialog-agent/typedialog-ag

Or build from source:

cargo build --release --package typedialog-ag

Setup

Set your API key:

export ANTHROPIC_API_KEY=your-api-key-here

Usage

Execute an Agent

Run an agent with interactive prompts for inputs:

typeagent agent.mdx

Or use the explicit run command:

typeagent run agent.mdx

Skip input prompts (use defaults):

typeagent agent.mdx --yes

Verbose output (show Nickel code):

typeagent agent.mdx --verbose

Validate an Agent

Check syntax, transpilation, and type checking without executing:

typeagent validate agent.mdx

Output:

✓ Validating agent

✓ MDX syntax valid
✓ Transpilation successful
✓ Type checking passed
✓ Evaluation successful

Agent Summary:
  Role: creative writer
  Model: claude-3-5-haiku-20241022
  Max tokens: 4096
  Temperature: 0.7

✓ Agent is valid and ready to execute

Transpile to Nickel

Convert MDX to Nickel configuration code:

# Output to stdout
typeagent transpile agent.mdx

# Save to file
typeagent transpile agent.mdx -o agent.ncl

Output:

{
  config = {
    role = "creative writer",
    llm = "claude-3-5-haiku-20241022",
  },
  inputs = {},
  template = "Write a haiku about {{ topic }}.",
}

Example Session

1. Create an Agent File

Create haiku.agent.mdx:

---
@agent {
  role: creative writer,
  llm: claude-3-5-haiku-20241022
}

@input topic: String
---

Write a haiku about {{ topic }}. Return only the haiku, nothing else.

2. Validate the Agent

$ typeagent validate haiku.agent.mdx

✓ Validating agent

✓ MDX syntax valid
✓ Transpilation successful
✓ Type checking passed
✓ Evaluation successful

Agent Summary:
  Role: creative writer
  Model: claude-3-5-haiku-20241022
  Max tokens: 4096
  Temperature: 0.7

✓ Agent is valid and ready to execute

3. Execute the Agent

$ typeagent haiku.agent.mdx

🤖 TypeAgent Executor

✓ Parsed agent definition
✓ Transpiled to Nickel
✓ Evaluated agent definition

Agent Configuration:
  Role: creative writer
  Model: claude-3-5-haiku-20241022
  Max tokens: 4096
  Temperature: 0.7

topic (String): programming in Rust

Inputs:
  topic: "programming in Rust"

⠋ Executing agent with LLM...
════════════════════════════════════════════════════════════
Response:
════════════════════════════════════════════════════════════

Memory safe code flows,
Ownership ensures no woes,
Concurrency glows.

════════════════════════════════════════════════════════════

Metadata:
  Duration: 1234ms
  Tokens: 87
  Validation: ✓ PASSED

Agent File Format

Basic Structure

---
@agent {
  role: <role>,
  llm: <model-name>
}

@input <name>: <type>
@input <name>?: <type>  # Optional input

@validate output {
  must_contain: ["pattern1", "pattern2"],
  format: markdown
}
---

Your template content with {{ variables }}.

Directives

@agent (Required)

Defines the agent configuration.

@agent {
  role: creative writer,
  llm: claude-3-5-haiku-20241022,
  tools: []  # Optional
}

Supported models:

• claude-3-5-haiku-20241022 - Fast, cheap
• claude-3-5-sonnet-20241022 - Balanced
• claude-opus-4 - Most capable

@input (Optional)

Declares inputs that will be prompted to the user.

@input name: String          # Required input
@input description?: String  # Optional input

@validate (Optional)

Defines output validation rules.

@validate output {
  must_contain: ["Security", "Performance"],
  must_not_contain: ["TODO", "FIXME"],
  format: markdown,
  min_length: 100,
  max_length: 5000
}

Supported formats:

• markdown (default)
• json
• yaml
• text

@import (Optional)

Import file content into template variables.

@import "./docs/**/*.md" as documentation
@import "https://example.com/schema.json" as schema

@shell (Optional)

Execute shell commands and inject output.

@shell "git diff HEAD~1" as recent_changes
@shell "cargo tree" as dependencies

Template Syntax

Uses Tera template engine:

# Variables
{{ variable_name }}

# Conditionals
{% if condition %}
  content
{% endif %}

# Filters
{{ name | upper }}
{{ value | default(value="fallback") }}

Commands

typeagent [FILE]

Execute an agent (default command).

Options:

• -y, --yes - Skip input prompts
• -v, --verbose - Show Nickel code
• -h, --help - Show help

Example:

typeagent agent.mdx --yes --verbose

typeagent run <FILE>

Explicit execute command (same as default).

Options:

• -y, --yes - Skip input prompts

Example:

typeagent run agent.mdx

typeagent validate <FILE>

Validate agent without execution.

Example:

typeagent validate agent.mdx

typeagent transpile <FILE>

Transpile MDX to Nickel.

Options:

• -o, --output <FILE> - Output file (default: stdout)

Example:

typeagent transpile agent.mdx -o agent.ncl

typeagent cache

Cache management (not yet implemented).

Subcommands:

• clear - Clear cache
• stats - Show cache statistics

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Anthropic API key for Claude models
RUST_LOG	No	Logging level (default: info)

Error Handling

Missing API Key

Error: ANTHROPIC_API_KEY environment variable not set
Set ANTHROPIC_API_KEY to use Claude models

Solution: Export your API key:

export ANTHROPIC_API_KEY=sk-ant-...

Invalid Agent File

Error: Failed to parse agent MDX

Solution: Validate your agent file:

typeagent validate agent.mdx

Validation Failures

Validation: ✗ FAILED
  - Output must contain: Security
  - Output too short: 45 chars (minimum: 100)

The agent executed successfully but output validation failed. Adjust your @validate rules or improve your prompt.

Examples

See typedialog-ag-core/tests/fixtures/ for example agent files:

• simple.agent.mdx - Basic hello world agent
• architect.agent.mdx - Architecture design agent with inputs
• code-reviewer.agent.mdx - Code review agent with shell commands

Troubleshooting

Command not found

Make sure the binary is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Or use the full path:

./target/release/typeagent

Permission denied

Make the binary executable:

chmod +x ./target/release/typeagent

Slow compilation

Use release mode for better performance:

cargo build --release --package typedialog-ag
./target/release/typeagent agent.mdx

Development

Run from source:

cargo run --package typedialog-ag -- agent.mdx

Run with logging:

RUST_LOG=debug cargo run --package typedialog-ag -- agent.mdx

License

MIT