User Guides

Comprehensive guides for building production-ready multi-agent systems with Flock.

---

📚 Core Guides

• 🤖 Agents

  ---

  Create specialized agents with type subscriptions, custom evaluation, and lifecycle hooks.

  Agent Guide

• 📋 Blackboard

  ---

  Master the shared artifact workspace that enables emergent agent collaboration.

  Blackboard Guide

• 🔒 Visibility Controls

  ---

  Control data access with public, private, tenant-based, and label-based visibility.

  Visibility Guide

• 📊 Dashboard

  ---

  Monitor agent execution in real-time with the built-in React dashboard.

  Dashboard Guide

---

🔍 Distributed Tracing

Comprehensive observability with OpenTelemetry and DuckDB.

• ⚡ Quick Start

  ---

  Enable tracing in 30 seconds and start capturing execution data.

  Tracing Quick Start

• 🔄 Auto-Tracing

  ---

  Automatic trace capture for all operations without code changes.

  Auto-Tracing Guide

• 📊 Unified Tracing

  ---

  Wrap workflows in single parent traces for better observability.

  Unified Tracing

• 🎯 Effective Usage

  ---

  Master debugging, optimization, and monitoring techniques.

  Using Tracing Effectively

• 🚀 Production

  ---

  Best practices for production deployments and monitoring.

  Production Tracing

• 📖 Reference

  ---

  Complete trace module and DuckDB schema reference.

  Trace Module

---

Guide Categories

Agent Development

• Creating Agents - Basic agent setup and configuration
• Declaring Consumption - Type subscriptions and patterns
• Advanced Subscriptions - Conditional consumption and filtering
• Agent Builder API - Complete reference

Blackboard Patterns

• Publishing to Blackboard - Add artifacts and data flows
• Batching Pattern - Parallel execution optimization
• Multi-Agent Coordination - Pipeline architectures
• Artifact Lifecycle - Data flow and management

Visibility & Security

• Visibility Overview - Understanding visibility controls
• Public Artifacts - Shared across all agents
• Tenant Isolation - Multi-tenant systems
• Label-Based Access - Fine-grained control
• Time-Based Access - Temporal constraints

Observability

• Trace Capture - Automatic trace collection
• Trace Analysis - Debugging workflows
• Dashboard Viewer - Visual trace exploration
• Production Monitoring - Metrics and alerts

---

Common Tasks

Looking for specific tasks? Here are quick links:

• Create a new agent → Agent Guide
• Enable parallel execution → Batching Pattern
• Debug agent execution → Tracing Effectively
• Add real-time monitoring → Dashboard Guide
• Implement multi-tenancy → Tenant Visibility
• Query artifacts → Blackboard Guide

---

Best Practices

Design Patterns

• ✅ Use small, focused agents with single responsibilities
• ✅ Leverage type contracts for implicit coordination
• ✅ Design artifacts as immutable domain events
• ✅ Enable batching for independent parallel work

Performance

• ✅ Use run_until_idle() after batching publishes
• ✅ Enable auto-tracing only in dev/staging
• ✅ Set appropriate trace TTL for storage management
• ✅ Filter trace services to reduce overhead

Production

• ✅ Implement proper visibility controls
• ✅ Monitor with production tracing
• ✅ Set up alerting on error rates
• ✅ Use correlation IDs for request tracking

---

Reference Documentation

• API Reference - Complete API documentation
• Configuration Reference - All configuration options
• Core Concepts - Foundational understanding

---

Need Help?

Can't find what you're looking for?

• 🔍 Search - Use the search bar (press / to focus)
• 💬 Ask - GitHub Discussions
• 🐛 Report - GitHub Issues

---

Start with the basics → Getting Started