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