docs

@falai/agent Documentation

Welcome to the @falai/agent documentation! This comprehensive framework enables you to build sophisticated, type-safe conversational AI agents with AI-powered routing, schema-driven data extraction, and declarative conversation flows.

✨ What Makes @falai/agent Unique

• 🤖 AI-Powered Routing: Intelligent route and step selection based on conversation context and user intent
• 🎯 Schema-First Data Collection: Type-safe, structured data extraction from natural conversations
• 🔀 Route DSL: Fluent, composable API for building complex multi-step conversation flows
• 🏗️ Type-Safe Context: Generic context management with lifecycle hooks and dynamic providers
• 🔄 Streaming & Tools: Real-time streaming responses with dynamic tool execution using unified Tool interface
• 💾 Comprehensive Persistence: Database-agnostic session and message storage across multiple adapters
• 🛠️ Unified Tool System: Simplified tool creation with flexible return types and powerful pattern helpers

📖 Documentation Structure

🚀 Getting Started

• Quick Start Guide - Build your first agent in 15 minutes

🏗️ Core Framework

Agent Architecture

• Agent Overview - Agent lifecycle, configuration & hooks
• Context Management - Dynamic context providers & updates
• Session Management - Session persistence & state
• Rules & Prohibitions - Agent-wide behavioral boundaries

AI Routing System

• Intelligent Routing - AI-powered route and step selection
• Route DSL - Declarative conversation flow design
• Step Transitions - Conditional logic and branching

Conversation Flows

• Routes - Route definition, lifecycle & completion
• Steps - Step configuration, data collection & validation
• Data Collection - Agent-level schema-driven data extraction

AI Integration

• AI Providers - Gemini, OpenAI, Anthropic, OpenRouter
• Prompt Composition - How prompts are built with context
• Response Processing - Schema extraction & tool calls

Tools & Execution

• Tool Definition - Creating and configuring tools
• Tool Scoping - Agent, route, and step-level tool management

Persistence

• Session Storage - Session persistence patterns
• Database Adapters - Built-in adapter configurations

Error Handling

• Error Handling - Comprehensive error handling patterns and recovery strategies
• Error Handling Patterns - Practical patterns for streaming, routing, and data sync errors

🚀 Advanced Guides

• Advanced Patterns - Complex use cases & integrations
• Migration Guides - Upgrade guides for major changes
• API Reference - Complete API documentation

🎯 Quick Links

By Learning Path

🚀 First time here? → Start with Quick Start Guide

🏗️ Understanding the design? → Read Agent Overview then Intelligent Routing

🤖 Building AI-powered conversations? → See Route DSL, Intelligent Routing, and Step Transitions

🎯 Collecting structured data? → Learn Agent-Level Data Collection and Schema-Driven Extraction

🔧 Working with tools? → See Tool Definition and Tool Scoping

💾 Need persistence? → See Session Storage and Database Adapters

🚀 Going to production? → Check Advanced Patterns and Server Session Management

By Topic

• Agent Architecture: Agent | Context | Sessions
• AI Routing System: Intelligent Routing | Route DSL | Step Transitions
• Conversation Flows: Routes | Steps | Agent-Level Data Collection
• AI Integration: Providers | Prompts | Responses
• Tools & Execution: Tool Definition | Tool Scoping
• Persistence: Session Storage | Adapters
• Error Handling: Core Error Handling | Error Patterns
• Advanced: Patterns | Migration | API Reference

💡 Examples by Domain

Check out the examples/ directory for complete, runnable examples organized by architectural domain:

🏗️ Core Concepts

• Basic Agent - Minimal agent setup and configuration
• Schema-Driven Extraction - Type-safe data collection with JSON Schema
• Session Management - Multi-turn conversations with persistence
• Modern Streaming API - Streaming responses with the modern API

🤖 AI Routing System

• Completion Transitions - Automatic route transitions when flows complete

💬 Conversation Flows

• Knowledge-Based Agent - Agents with domain-specific knowledge bases
• Persistent Onboarding - Multi-step onboarding with data persistence

🤖 AI Providers

• OpenAI Integration - GPT-4 and GPT-3.5 Turbo with backup models
• Anthropic Integration - Claude with streaming and tool calling

🔧 Tools & Execution

• Basic Tools - Unified Tool interface with simple return values
• Data Enrichment Tools - Pattern helpers for data modification

💾 Persistence

• Memory Sessions - In-memory session management
• Redis Persistence - High-performance Redis storage
• Database Persistence - SQL/NoSQL database integration
• Custom Adapter - Build custom persistence adapters

🚀 Advanced Patterns

• Streaming Responses - Real-time response streaming
• Route Lifecycle Hooks - Custom route behavior and data transformation

🔗 Integrations

• Database Integration - Direct database access patterns
• Healthcare Integration - Domain-specific healthcare workflows
• Search Integration - Integration with search engines
• Server Session Management - Server-side session handling

🤝 Contributing

We welcome contributions to improve the documentation and examples! Here's how you can help:

Ways to Contribute

• 📝 Improve Documentation - Fix typos, clarify explanations, add examples
• 🎯 Create Examples - Add examples for new use cases or domains
• 🔧 Update Code Samples - Ensure examples work with latest framework versions
• 📚 Write Guides - Create tutorials for specific patterns or integrations
• 🐛 Report Issues - Found a bug in docs or examples? Let us know!

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/your-username/agent.git
3. Install dependencies: bun install
4. Make changes in the appropriate domain directory
5. Test examples by running them: bun run examples/your-example.ts
6. Submit a pull request

Documentation Structure

When adding new content, follow the domain-focused organization:

docs/
├── core/                    # Core framework docs
│   ├── agent/              # Agent architecture & lifecycle
│   ├── routing/            # AI routing system & intelligent selection
│   ├── conversation-flows/ # Route DSL, steps, data collection
│   ├── ai-integration/     # Providers, prompts, response processing
│   ├── tools/              # Tool definition, execution, scoping
│   └── persistence/        # Session storage & database adapters
└── guides/                 # End-to-end guides
    └── [guide-name]/       # getting-started, building-agents, etc.

examples/
├── core-concepts/          # Basic agent setup & fundamental concepts
├── ai-providers/           # AI provider integrations
├── conversation-flows/     # AI routing & conversation patterns
├── persistence/            # Session storage implementations
├── tools/                  # Tool creation & execution patterns
├── advanced-patterns/      # Complex use cases & integrations
└── integrations/           # External service integrations

Example Contribution Workflow

1. Identify the domain your example belongs to (e.g., tools, persistence)
2. Create the example in the appropriate domain directory
3. Add comprehensive comments explaining the concepts
4. Include error handling and best practices
5. Update documentation links if needed
6. Test thoroughly before submitting

Need Help?

• 📖 Contributing Guide - Detailed contribution guidelines
• 💬 Discussions - Ask questions and get help
• 🐛 Issues - Report bugs or request features

---

Made with ❤️ for the community