More at guides.raaf-ai.dev:

Ruby AI Agents Factory (RAAF) Guides

These guides are designed to make you immediately productive with RAAF, and to help you understand how all of the pieces fit together to build sophisticated AI agent systems.

RAAF is a comprehensive Ruby framework for building AI agents with 100% Python OpenAI Agents SDK feature parity, plus enterprise-grade capabilities for production workflows.

Guide Features

  • Practical Examples: Every guide includes working code examples you can run immediately
  • Progressive Learning: Guides build on each other, from basic concepts to advanced patterns
  • Production Focus: Learn patterns and practices used in real-world AI applications
  • Enterprise Grade: Security, compliance, and monitoring are built into every guide
  • Multi-Provider: Examples work with OpenAI, Anthropic, Groq, and 100+ other providers
Guides marked with this icon are currently being worked on and will not be available in the Guides Index menu. While still useful, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections.

Start Here

New to RAAF? Start with these foundational guides to understand the core concepts and get your first AI agent running.

Origins of RAAF
Work in progress

The story behind Ruby AI Agents Factory (RAAF) and how it came to be. Learn about the business challenge that sparked RAAF's creation, the AI-assisted development approach, and how RAAF evolved from experiment to production platform with Python SDK compatibility.

Overview
Work in progress

Introduction to Ruby AI Agents Factory (RAAF) and its core concepts. Learn about RAAF's philosophy, architecture, and how it compares to other AI frameworks. Understand the modular design, provider-agnostic approach, and enterprise-ready features.

Getting Started with RAAF
Work in progress

Everything you need to know to install RAAF and create your first AI agent. Learn how to set up your development environment, create basic agents, add tools, and build your first multi-agent workflow. Includes practical examples and troubleshooting.

You'll learn: Environment setup, creating your first agent, adding tools, and basic troubleshooting.

Core Guide
Work in progress

Deep dive into agents, runners, tools, and the fundamental patterns for building AI systems. Understand the agent lifecycle, execution model, message handling, and core design patterns. Learn about configuration, error handling, and best practices for agent development.

Core Components

Build sophisticated AI systems with RAAF's core components. Learn about tools, multi-agent workflows, and provider integrations.

Tools Guide
Work in progress

Tools enable agents to interact with external systems and perform computations. Learn about built-in tools (web search, file operations, code execution), how to create custom tools, tool security patterns, and advanced tool integration techniques.

Multi-Agent Workflows
Work in progress

Build sophisticated multi-agent systems where specialized agents work together to solve complex problems through handoffs and collaboration. Learn about agent orchestration, handoff patterns, state management, and scaling multi-agent systems.

You'll learn: Agent orchestration, handoff patterns, state management, and scaling strategies.

DSL Guide
Work in progress

Use the declarative Domain Specific Language for elegant, Ruby-idiomatic agent configuration and tool definition. Learn DSL syntax, agent builders, tool definitions, and advanced DSL patterns for complex workflows.

Providers Guide
Work in progress

RAAF supports 100+ AI providers. Learn how to use different providers, optimize costs, and implement failover strategies. Understand provider configuration, model selection, cost optimization, and building resilient AI systems.

Enterprise Features

Production-ready enterprise capabilities including security, compliance, monitoring, and memory management for scalable AI systems.

Guardrails Guide
Work in progress

Comprehensive security and safety system for AI agents. Learn about input/output filtering, PII detection, content moderation, and compliance enforcement. Understand security patterns, threat detection, data privacy, and building secure AI applications.

Memory Guide
Work in progress

Advanced memory management and context persistence for AI agents. Learn about different storage backends, pruning strategies, and semantic search. Understand memory optimization, context windows, and building conversational AI systems.

Tracing Guide
Work in progress

Comprehensive monitoring and observability for AI systems with Python SDK compatibility. Learn about span tracing, metrics collection, performance monitoring, and building production-ready AI systems with full observability and debugging capabilities.

Compliance Guide
Work in progress

Enterprise compliance frameworks including GDPR, HIPAA, and SOC2. Learn about automated audit trails, policy enforcement, regulatory compliance, and building enterprise-grade AI systems that meet industry standards.

Integration & Development

Integrate RAAF into your applications with Rails, streaming, testing, and development best practices.

Rails Integration
Work in progress

Integrate AI agents into Rails applications with web dashboards, real-time monitoring, and seamless controller integration. Learn about Rails patterns, ActionCable integration, background jobs, and building full-stack AI applications.

Streaming Guide
Work in progress

Real-time streaming responses, async processing, WebSocket integration, and event-driven agent architectures. Learn about streaming patterns, async workflows, real-time UIs, and building responsive AI applications.

Testing Guide
Work in progress

Test AI agents effectively with mock providers, RSpec integration, and comprehensive testing strategies for multi-agent systems. Learn about unit testing, integration testing, mocking strategies, and ensuring AI system reliability.

Advanced Topics

Scale and optimize your AI systems with advanced topics covering performance, deployment, cost management, and troubleshooting.

Performance Optimization
Work in progress

Optimize RAAF applications for speed, scalability, and cost efficiency. Learn about connection pooling, caching, provider routing, resource management, and building high-performance AI systems that scale under load.

You'll learn: Connection pooling, caching, resource management, and high-performance AI systems.

Deployment Guide
Work in progress

Deploy RAAF agents to production with Docker, Kubernetes, monitoring, and best practices for scalable AI systems. Learn about containerization, orchestration, CI/CD pipelines, and production deployment strategies.

You'll learn: Containerization, orchestration, CI/CD pipelines, and production deployment strategies.

Cost Management
Work in progress

Control and optimize AI costs with provider routing, token management, and comprehensive cost tracking strategies. Learn about budget controls, cost analytics, provider optimization, and building cost-effective AI solutions.

You'll learn: Budget controls, cost analytics, provider optimization, and cost-effective AI solutions.

Troubleshooting Guide
Work in progress

Common issues, debugging techniques, and solutions for RAAF applications. Learn about error diagnosis, performance debugging, provider issues, and resolving complex problems in AI agent systems.

Maintenance Policy
Work in progress

RAAF version support policy, release schedule, and upgrade guidelines. Learn about version lifecycles, security updates, upgrade strategies, and planning for long-term maintenance of RAAF applications.

Reference

Complete reference documentation for APIs, configuration options, tools, and maintenance policies.

API Reference
Work in progress

Complete API documentation for all RAAF classes and modules. Comprehensive method signatures, parameters, return values, and practical usage examples for every class in the RAAF ecosystem.

Configuration Reference
Work in progress

Comprehensive reference for all RAAF configuration options, environment variables, and settings. Learn about all configuration parameters, their effects, security considerations, and production setup.

Tool Reference
Work in progress

Reference documentation for all built-in tools and their configuration options and usage patterns. Complete catalog of available tools, their parameters, security considerations, and integration examples.

Examples & Patterns

Real-world examples and proven patterns for common use cases, architecture patterns, and best practices.

Common Use Cases
Work in progress

Real-world examples and patterns for common AI agent use cases including customer service, data analysis, and content creation. Learn through practical examples, implementation strategies, and proven patterns for business applications.

Best Practices
Work in progress

Comprehensive best practices for building, deploying, and maintaining production AI agent systems with RAAF. Learn about code organization, security patterns, performance optimization, and operational excellence.



Back to top