TypeDialog/agents/README.md

TypeDialog Agent Examples

This directory contains example agents demonstrating various capabilities of the TypeDialog Agent system.

Available Agents

1. greeting.agent.mdx

Purpose: Simple friendly greeting Inputs: name (String) LLM: Claude 3.5 Haiku

Usage:

# CLI
typedialog-ag agents/greeting.agent.mdx

# HTTP
curl -X POST http://localhost:8765/agents/greeting/execute \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice"}'

2. code-reviewer.agent.mdx

Purpose: Comprehensive code review Inputs: language (String), code (String) LLM: Claude Opus 4.5 Validation: Must contain "## Review" and "## Suggestions"

Usage:

curl -X POST http://localhost:8765/agents/code-reviewer/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "rust",
    "code": "fn add(a: i32, b: i32) -> i32 { a + b }"
  }'

3. architect.agent.mdx

Purpose: Software architecture design Inputs: feature (String), tech_stack? (String, optional) LLM: Claude Opus 4.5 Validation: Must contain "## Architecture", "## Components", "## Data Flow"

Usage:

curl -X POST http://localhost:8765/agents/architect/execute \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "Real-time chat system",
    "tech_stack": "Rust, WebSockets, PostgreSQL"
  }'

4. summarizer.agent.mdx

Purpose: Text summarization Inputs: text (String), style? (String, optional) LLM: Claude 3.5 Sonnet

Usage:

curl -X POST http://localhost:8765/agents/summarizer/execute \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Long article text here...",
    "style": "technical"
  }'

5. test-generator.agent.mdx

Purpose: Generate unit tests Inputs: language (String), function_code (String) LLM: Claude 3.5 Sonnet Validation: Must contain "test" and "assert"

Usage:

curl -X POST http://localhost:8765/agents/test-generator/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "function_code": "def factorial(n):\\n    return 1 if n == 0 else n * factorial(n-1)"
  }'

6. doc-generator.agent.mdx

Purpose: Generate technical documentation Inputs: code (String), language (String) LLM: Claude 3.5 Sonnet

Usage:

curl -X POST http://localhost:8765/agents/doc-generator/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "javascript",
    "code": "function debounce(fn, delay) { ... }"
  }'

7. translator.agent.mdx

Purpose: Language translation Inputs: text (String), source_lang (String), target_lang (String) LLM: Claude 3.5 Sonnet

Usage:

curl -X POST http://localhost:8765/agents/translator/execute \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_lang": "English",
    "target_lang": "Spanish"
  }'

8. debugger.agent.mdx

Purpose: Debug code issues Inputs: code (String), error (String), language (String) LLM: Claude Opus 4.5 Validation: Must contain "## Root Cause" and "## Fix"

Usage:

curl -X POST http://localhost:8765/agents/debugger/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "rust",
    "code": "let x = vec![1,2,3]; println!(\"{}\", x[5]);",
    "error": "index out of bounds: the len is 3 but the index is 5"
  }'

9. refactor.agent.mdx

Purpose: Code refactoring Inputs: code (String), language (String), goal? (String, optional) LLM: Claude Opus 4.5 Validation: Must contain "## Refactored Code" and "## Changes"

Usage:

curl -X POST http://localhost:8765/agents/refactor/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "typescript",
    "code": "function calc(a,b,op){if(op==='+')return a+b;if(op==='-')return a-b;}",
    "goal": "Improve readability and type safety"
  }'

Features Demonstrated

Input Types

• Required inputs: name, code, language
• Optional inputs: style?, tech_stack?, goal?

LLM Models

• Claude 3.5 Haiku: Fast, cost-effective (greeting)
• Claude 3.5 Sonnet: Balanced performance (summarizer, test-generator, doc-generator, translator)
• Claude Opus 4.5: Maximum capability (code-reviewer, architect, debugger, refactor)

Validation Rules

• must_contain: Ensure specific sections in output
• format: Enforce output format (markdown, text)
• min_length/max_length: Control output size

Temperature Settings

• 0.3: Deterministic, factual (code review, debugging, translation)
• 0.4-0.5: Balanced creativity (architecture, refactoring)
• 0.8: More creative (greeting)

Max Tokens

• 150: Short responses (greeting)
• 500-1000: Medium responses (summarizer, translator)
• 2000-3000: Detailed responses (code review, documentation)
• 4000: Comprehensive responses (architecture)

Testing Agents

CLI Testing

# Validate agent
typedialog-ag validate agents/greeting.agent.mdx

# Transpile to Nickel
typedialog-ag transpile agents/greeting.agent.mdx

# Execute (interactive)
typedialog-ag agents/greeting.agent.mdx

HTTP Server Testing

# Start server
typedialog-ag serve --port 8765

# Test health
curl http://localhost:8765/health

# Validate agent
curl -X POST http://localhost:8765/validate \
  -H "Content-Type: application/json" \
  -d '{"agent_file":"agents/greeting.agent.mdx"}'

# Execute agent
curl -X POST http://localhost:8765/agents/greeting/execute \
  -H "Content-Type: application/json" \
  -d '{"name":"World"}'

Best Practices

1. Clear Role: Define specific role in @agent directive
2. Type Inputs: Declare input types explicitly
3. Validate Output: Use @validate to ensure quality
4. Right Model: Choose LLM based on task complexity
5. Temperature: Lower for factual, higher for creative
6. Token Limits: Set appropriate max_tokens for task
7. Prompts: Be specific and provide clear instructions
8. Examples: Include examples in prompt when helpful

Environment Variables

Ensure you have API keys configured:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...  # If using OpenAI models

Cache

The system automatically caches transpiled Nickel code:

# Check cache stats
typedialog-ag cache stats

# Clear cache
typedialog-ag cache clear

Cache location: ~/.typeagent/cache/