TypeDialog Agent Documentation

User guide for TypeDialog Agent - Execute AI agents defined as markdown files with multi-provider LLM support.

What is TypeDialog Agent

TypeDialog Agent (typedialog-ag) is a CLI tool that allows you to:

Define AI agents as markdown files (.agent.mdx)
Execute them with multiple LLM providers (Claude, OpenAI, Gemini, Ollama)
Inject context from files, shell commands, and templates
Validate outputs automatically
Stream responses in real-time

Quick Links

Getting Started

getting-started.md - Installation and first agent
AGENTS.md - How to write agent files
CLI_REFERENCE.md - Command reference

LLM Providers

llm-providers.md - Complete provider guide
- Claude (Anthropic)
- OpenAI (GPT)
- Google Gemini
- Ollama (local models)

Advanced Topics

TEMPLATES.md - Template system and variables
VALIDATION.md - Output validation rules
BEST_PRACTICES.md - Tips and patterns

Quick Start

1. Install

# Build from source
cargo build --release --package typedialog-ag

# The binary will be at: target/release/typedialog-ag
```text

### 2. Set API Key

```bash
# For Claude
export ANTHROPIC_API_KEY=sk-ant-...

# For OpenAI
export OPENAI_API_KEY=sk-...

# For Gemini
export GEMINI_API_KEY=...

# For Ollama (local - no API key needed)
ollama serve
```text

### 3. Create Your First Agent

Create `hello.agent.mdx`:

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

@input name: String
---

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

### 4. Run It

```bash
typedialog-ag hello.agent.mdx
# Prompts: name (String): Alice
# Output: Hello Alice! It's wonderful to meet you...
```text

## Documentation Structure

```text
docs/agent/
├── README.md              ← Overview (you are here)
├── getting-started.md     ← Installation & first steps
├── AGENTS.md              ← Writing agent files
├── llm-providers.md       ← Provider setup & comparison
├── CLI_REFERENCE.md       ← Command-line reference
├── TEMPLATES.md           ← Template system guide
├── VALIDATION.md          ← Output validation
└── BEST_PRACTICES.md      ← Tips & patterns
```text

## Features

### Multi-Provider Support

Choose the best LLM for your task:

- **Claude** - Best for code, analysis, reasoning
- **OpenAI** - Excellent code understanding, broad capabilities
- **Gemini** - Creative tasks, multi-modal
- **Ollama** - Privacy-first, local execution, no costs

### Context Injection

Import context from multiple sources:

```yaml
@import "./src/**/*.rs" as code        # File imports
@shell "git status" as git_status      # Shell commands
@import ".env" as environment          # Configuration
```text

### Template System

Powerful templating with LiquidJS:

```markdown
Hello {{name}}!

{{#if premium}}
  Welcome to premium features!
{{else}}
  Upgrade to unlock more!
{{/if}}
```text

### Output Validation

Ensure quality automatically:

```yaml
@validate output {
  must_contain: ["## Summary", "## Recommendations"],
  format: markdown,
  min_length: 500
}
```text

### Real-time Streaming

See responses as they're generated with token-by-token streaming.

## Examples

### Code Review

```bash
typedialog-ag examples/12-agent-execution/code-review.agent.mdx
```text

### Documentation Generation

```bash
typedialog-ag examples/12-agent-execution/documentation.agent.mdx
```text

### Task Planning

```bash
typedialog-ag examples/12-agent-execution/task-planner.agent.mdx
```text

### Local Privacy Analysis

```bash
# Runs entirely locally with Ollama
typedialog-ag examples/12-agent-execution/local-privacy.agent.mdx
```text

See [examples/12-agent-execution/](../../examples/12-agent-execution/) for all examples.

## Use Cases

### Development

- Code reviews
- Refactoring assistance
- Documentation generation
- Bug analysis
- Architecture design

### Content Creation

- Blog posts
- Documentation
- Technical writing
- Creative content

### Business

- Task planning
- Process documentation
- Decision support
- Data analysis

### Privacy-Sensitive

- Local data analysis with Ollama
- Compliance review
- Sensitive document processing

## Learning Path

```text
1. getting-started.md
   ↓ Install and run first agent

2. AGENTS.md
   ↓ Learn agent file format

3. llm-providers.md
   ↓ Choose your provider

4. TEMPLATES.md
   ↓ Master template system

5. Examples & Demos
   ↓ See real-world usage

6. BEST_PRACTICES.md
   ↓ Optimize your agents
```text

## Resources

### Examples & Demos

- [Examples](../../examples/12-agent-execution/README.md) - 8 practical use cases
- [Demos](../../demos/agent/README.md) - Provider comparison demos
- [Tests](../../tests/agent/README.md) - Validation tests

### Technical Documentation

- [LLM Integration](llm-integration.md) - Complete technical guide
- [Core Examples](../../crates/typedialog-agent/typedialog-ag-core/examples/) - Rust API usage
- [Developer Docs](../../crates/typedialog-agent/README.md) - Architecture and APIs

### Main Project

- [TypeDialog README](../../README.md) - Project overview
- [Examples](../../examples/README.md) - All project examples

## Common Questions

### Which LLM provider should I use

See [llm-providers.md](llm-providers.md#choosing-a-provider) for a detailed comparison.

**Quick guide:**

- **Quick tasks** → Claude Haiku
- **Code work** → Claude Sonnet or GPT-4o
- **Creative** → Gemini 2.0
- **Privacy** → Ollama (local)

### How much does it cost

- **Claude** - Pay per token (see Anthropic pricing)
- **OpenAI** - Pay per token (see OpenAI pricing)
- **Gemini** - Free tier + pay per token
- **Ollama** - Free (runs locally)

See [llm-providers.md](llm-providers.md#cost-comparison) for details.

### Can I use it offline

Yes. Use Ollama for completely offline operation:

```bash
ollama serve
ollama pull llama2
typedialog-ag my-agent.agent.mdx  # Uses llama2 locally
```text

### Is my data private

- **Cloud providers** (Claude, OpenAI, Gemini) - Data sent to their APIs
- **Ollama** - Completely private, runs on your machine

See [BEST_PRACTICES.md](BEST_PRACTICES.md#privacy-considerations) for guidance.

## Getting Help

### Documentation

1. Read [getting-started.md](getting-started.md)
2. Check [CLI_REFERENCE.md](CLI_REFERENCE.md)
3. Browse [examples](../../examples/12-agent-execution/)

### Troubleshooting

See [getting-started.md#troubleshooting](getting-started.md#troubleshooting)

### Contributing

See [Developer Documentation](../../crates/typedialog-agent/README.md)

## What's Next

Ready to get started? → [getting-started.md](getting-started.md)

Want to understand agent files? → [AGENTS.md](AGENTS.md)

Need to choose a provider? → [llm-providers.md](llm-providers.md)

---

**Version**: 0.1.0
**Last Updated**: December 2024

6.9 KiB Raw Blame History

TypeDialog Agent Documentation

What is TypeDialog Agent

Quick Links

Getting Started

LLM Providers

Advanced Topics

Quick Start

1. Install

6.9 KiB

Raw Blame History