TypeDialog/crates/typedialog-agent/quickstart.md

# TypeAgent Quick Start

Get started with TypeAgent in 5 minutes.

## Prerequisites

- Rust toolchain (1.75+)
- Anthropic API key

## Setup

### 1. Set API Key

```bash
export ANTHROPIC_API_KEY=your-api-key-here
```

### 2. Build TypeAgent

```bash
cd crates/typedialog-agent/typedialog-ag
cargo build --release
```

### 3. Add to PATH (optional)

```bash
export PATH="$PWD/target/release:$PATH"
```

## Your First Agent

### Create an Agent File

Create `hello.agent.mdx`:

```markdown
---
@agent {
  role: friendly assistant,
  llm: claude-3-5-haiku-20241022
}

@input name: String
---

Say hello to {{ name }} in a creative and friendly way!
```

### Run It

```bash
typeagent hello.agent.mdx
```

You'll see:

```
🤖 TypeAgent Executor

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

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

name (String): Alice█
```

Type a name and press Enter. The agent will execute and show the response!

## Next Steps

### Try the Examples

```bash
# Simple greeting
typeagent tests/fixtures/simple.agent.mdx --yes

# Creative haiku
typeagent tests/fixtures/haiku.agent.mdx
```

### Validate Before Running

```bash
typeagent validate hello.agent.mdx
```

### See the Nickel Code

```bash
typeagent transpile hello.agent.mdx
```

## Common Workflows

### Development Workflow

```bash
# 1. Write your agent
vim agent.mdx

# 2. Validate it
typeagent validate agent.mdx

# 3. Test with verbose output
typeagent agent.mdx --verbose

# 4. Run in production
typeagent agent.mdx
```

### Quick Iteration

Use `--yes` to skip prompts during development:

```bash
# Edit agent.mdx
# Run without prompts
typeagent agent.mdx --yes
```

## Advanced Features

### Context Injection

Import files into your agent:

```markdown
@import "./docs/**/*.md" as documentation
@shell "git log --oneline -5" as recent_commits
```

### Output Validation

Ensure output meets requirements:

```markdown
@validate output {
  must_contain: ["Security", "Performance"],
  format: markdown,
  min_length: 100
}
```

### Conditional Logic

Use Tera template syntax:

```markdown
{% if has_description %}
Description: {{ description }}
{% endif %}
```

## Troubleshooting

### "ANTHROPIC_API_KEY not set"

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

### "Failed to parse agent MDX"

Check your frontmatter syntax:

```markdown
---
@agent {
  role: assistant,  # <- comma required
  llm: claude-3-5-haiku-20241022
}
---
```

### "Permission denied"

```bash
chmod +x ./target/release/typeagent
```

## Learn More

- [CLI Documentation](typedialog-ag/README.md)
- [LLM Integration Guide](typedialog-ag-core/LLM_INTEGRATION.md)
- [Example Agents](typedialog-ag-core/tests/fixtures/)

## Support

- GitHub Issues: https://github.com/jesusperezlorenzo/typedialog/issues
- API Docs: `cargo doc --open --package typedialog-ag-core`

## Next Example: Architecture Agent

Create `architect.agent.mdx`:

```markdown
---
@agent {
  role: software architect,
  llm: claude-3-5-sonnet-20241022
}

@input feature_name: String
@input requirements?: String

@validate output {
  must_contain: ["## Architecture", "## Components"],
  format: markdown,
  min_length: 200
}
---

# Architecture Design: {{ feature_name }}

You are an experienced software architect. Design a comprehensive architecture for:

**Feature**: {{ feature_name }}

{% if requirements %}
**Requirements**: {{ requirements }}
{% endif %}

Provide:
1. High-level architecture overview
2. Component breakdown
3. Data flow
4. Technology recommendations

Use clear markdown formatting with sections.
```

Run it:

```bash
typeagent architect.agent.mdx
```

The agent will prompt for inputs and generate a complete architecture design!