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**:
```bash
# 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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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**:
```bash
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
```bash
# 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
```bash
# 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:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...  # If using OpenAI models
```

## Cache

The system automatically caches transpiled Nickel code:
```bash
# Check cache stats
typedialog-ag cache stats

# Clear cache
typedialog-ag cache clear
```

Cache location: `~/.typeagent/cache/`