The production-grade GenAI metaframework built on Pydantic AI.

Copyright 2026 Firefly Software Foundation. Licensed under the Apache License 2.0.

• Why fireflyframework-agentic?
• Key Principles
• Architecture at a Glance
• Feature Highlights
• Requirements
• Installation
  • One-Line Installer (Recommended)
  • Install from Source
  • Optional Extras
  • Verify Installation
  • Uninstall
• 5-Minute Quick Start
• Using in Jupyter Notebooks
• Learn the Framework
• Development
• Contributing
• License

Pydantic AI provides an excellent foundation: type-safe, model-agnostic agents with structured output. But a production GenAI system demands far more than a single agent call. You need to orchestrate multi-step reasoning, validate and retry LLM outputs against schemas, manage conversation memory across turns, observe every call with traces and metrics, run A/B experiments to compare models, and expose the whole thing over REST or message queues — all without coupling your domain logic to infrastructure concerns.

fireflyframework-agentic is the production framework built on top of Pydantic AI. It extends the engine with six composable layers — from core configuration through agent management, intelligent reasoning, experimentation, pipeline orchestration, and service exposure — so that every concern has a dedicated, protocol-driven module. You write your business logic; the framework provides the architecture.

What "metaframework" means in practice:

• You keep Pydantic AI's familiar Agent, Tool, and RunContext APIs unchanged.
• The framework wraps them with lifecycle hooks, registries, delegation routers, memory managers, reasoning patterns, validation loops, DAG pipelines, and exposure endpoints — all optional, all composable, all swappable through Python protocols.
• No vendor lock-in: switch models, swap memory backends, or replace the REST layer without touching your agent code.

1. Protocol-driven contracts — Every extension point is defined as a @runtime_checkable Protocol or abstract base class. The framework ships thirteen protocols (AgentLike, ToolProtocol, GuardProtocol, ReasoningPattern, DelegationStrategy, StepExecutor, CompressionStrategy, MemoryStore, ValidationRule, Chunker, EmbeddingProtocol, VectorStoreProtocol, QueueConsumer / QueueProducer) so you can swap or extend any component without modifying framework internals.

2. Convention over configuration — Sensible defaults everywhere. FireflyAgenticConfig is a Pydantic Settings singleton that reads from environment variables prefixed with FIREFLY_AGENTIC_ and .env files. One config object governs model defaults, retry counts, token limits, observability endpoints, memory backends, and validation thresholds — override only what you need.

3. Layered composition — Six layers with strict top-down dependency flow: Core → Agent → Intelligence → Experimentation → Orchestration → Exposure. Higher layers depend on lower layers but never the reverse, keeping the dependency graph acyclic and each module independently testable.

4. Optional dependencies — Heavy libraries (fastapi, aiokafka, aio-pika, redis, chromadb, pinecone, openai) are declared as pip extras ([rest], [kafka], [rabbitmq], [redis], [openai-embeddings], [vectorstores-chroma], [all]). The core framework imports them lazily inside factory functions so that you install only what your deployment requires.

graph TD
    subgraph Exposure Layer
        REST["REST API<br/><small>create_agentic_app · SSE streaming<br/>health · middleware · router</small>"]
        QUEUES["Message Queues<br/><small>Kafka · RabbitMQ · Redis<br/>consumers · producers · QueueRouter</small>"]
    end

    subgraph Orchestration Layer
        PIPE["Pipeline / DAG Engine<br/><small>DAG · DAGNode · DAGEdge<br/>PipelineEngine · PipelineBuilder<br/>AgentStep · ReasoningStep · CallableStep<br/>FanOutStep · FanInStep<br/>EmbeddingStep · RetrievalStep</small>"]
    end

    subgraph Embeddings / Vector Stores
        EMB["Embeddings<br/><small>EmbeddingProtocol · BaseEmbedder<br/>OpenAI · Azure · Cohere · Google<br/>Mistral · Voyage · Bedrock · Ollama<br/>EmbedderRegistry · similarity</small>"]
        VS["Vector Stores<br/><small>VectorStoreProtocol · BaseVectorStore<br/>InMemory · ChromaDB · Pinecone · Qdrant<br/>VectorStoreRegistry · search_text</small>"]
    end

    subgraph Experimentation Layer
        EXP["Experiments<br/><small>Experiment · Variant<br/>ExperimentRunner · VariantComparator<br/>ExperimentTracker</small>"]
        LAB["Lab<br/><small>LabSession · Benchmark<br/>EvalOrchestrator · EvalDataset<br/>ModelComparison</small>"]
    end

    subgraph Intelligence Layer
        REASON["Reasoning Patterns<br/><small>ReAct · CoT · PlanAndExecute<br/>Reflexion · ToT · GoalDecomposition<br/>ReasoningPipeline</small>"]
        VAL["Validation & QoS<br/><small>OutputReviewer · OutputValidator<br/>ConfidenceScorer · ConsistencyChecker<br/>GroundingChecker · 5 rule types</small>"]
        OBS["Observability<br/><small>FireflyTracer · FireflyMetrics<br/>FireflyEvents · UsageTracker<br/>CostCalculator · @traced · @metered<br/>configure_exporters</small>"]
        EXPL["Explainability<br/><small>TraceRecorder · ExplanationGenerator<br/>AuditTrail · ReportBuilder</small>"]
    end

    subgraph Agent Layer
        AGT["Agents<br/><small>FireflyAgent · AgentRegistry<br/>DelegationRouter · AgentLifecycle<br/>@firefly_agent · 5 templates</small>"]
        TOOLS["Tools<br/><small>BaseTool · ToolBuilder · ToolKit<br/>5 guards · 3 composers<br/>ToolRegistry · 9 built-ins</small>"]
        PROMPTS["Prompts<br/><small>PromptTemplate · PromptRegistry<br/>3 composers · PromptValidator<br/>PromptLoader</small>"]
        CONTENT["Content<br/><small>TextChunker · DocumentSplitter<br/>ImageTiler · BatchProcessor<br/>ContextCompressor · SlidingWindowManager</small>"]
        MEM["Memory<br/><small>MemoryManager · ConversationMemory<br/>WorkingMemory · TokenEstimator<br/>InMemoryStore · FileStore</small>"]
    end

    subgraph Core Layer
        CFG["Config<br/><small>FireflyAgenticConfig<br/>get_config · reset_config</small>"]
        TYPES["Types & Protocols<br/><small>AgentLike · 10 protocols<br/>TypeVars · type aliases</small>"]
        EXC["Exceptions<br/><small>FireflyAgenticError hierarchy<br/>18 exception classes</small>"]
        PLUG["Plugin System<br/><small>PluginDiscovery<br/>3 entry-point groups</small>"]
    end

    REST --> PIPE
    QUEUES --> PIPE
    PIPE --> AGT
    PIPE --> REASON
    PIPE --> VAL
    PIPE --> EMB
    PIPE --> VS
    VS --> EMB
    EMB --> CFG
    VS --> CFG
    EXP --> AGT
    LAB --> EXP
    REASON --> AGT
    OBS --> AGT
    EXPL --> OBS
    VAL --> AGT
    AGT --> TOOLS
    AGT --> PROMPTS
    AGT --> CONTENT
    AGT --> MEM
    AGT --> CFG
    TOOLS --> CFG
    PROMPTS --> CFG
    CONTENT --> CFG
    MEM --> CFG
    REASON --> CFG
    VAL --> CFG

Every extension point is a @runtime_checkable protocol. Implement the protocol to create your own components; the framework discovers them via duck typing.

classDiagram
    class AgentLike {
        <<Protocol>>
        +run(prompt, **kwargs) Any
    }
    class ToolProtocol {
        <<Protocol>>
        +name: str
        +description: str
        +execute(**kwargs) Any
    }
    class GuardProtocol {
        <<Protocol>>
        +check(tool_name, kwargs) GuardResult
    }
    class ReasoningPattern {
        <<Protocol>>
        +execute(agent, input, **kwargs) ReasoningResult
    }
    class StepExecutor {
        <<Protocol>>
        +execute(context, inputs) Any
    }
    class DelegationStrategy {
        <<Protocol>>
        +select(agents, prompt, **kwargs) Any
    }
    class CompressionStrategy {
        <<Protocol>>
        +compress(text, max_tokens) str
    }
    class MemoryStore {
        <<Protocol>>
        +save(namespace, entry)
        +load(namespace) list
        +delete(namespace, entry_id)
        +clear(namespace)
    }
    class ValidationRule {
        <<Protocol>>
        +name: str
        +validate(value) ValidationRuleResult
    }
    class QueueConsumer {
        <<Protocol>>
        +start()
        +stop()
    }
    class QueueProducer {
        <<Protocol>>
        +publish(message)
    }
    class EmbeddingProtocol {
        <<Protocol>>
        +embed(texts) EmbeddingResult
        +embed_one(text) list~float~
    }
    class VectorStoreProtocol {
        <<Protocol>>
        +upsert(documents, namespace)
        +search(query_embedding, top_k) list~SearchResult~
        +search_text(query, top_k) list~SearchResult~
        +delete(ids, namespace)
    }

    AgentLike <|.. FireflyAgent
    AgentLike <|.. pydantic_ai.Agent
    ToolProtocol <|.. BaseTool
    ToolProtocol <|.. SequentialComposer
    ToolProtocol <|.. FallbackComposer
    ToolProtocol <|.. ConditionalComposer
    GuardProtocol <|.. ValidationGuard
    GuardProtocol <|.. RateLimitGuard
    GuardProtocol <|.. ApprovalGuard
    GuardProtocol <|.. SandboxGuard
    GuardProtocol <|.. CompositeGuard
    ReasoningPattern <|.. AbstractReasoningPattern
    ReasoningPattern <|.. ReasoningPipeline
    StepExecutor <|.. AgentStep
    StepExecutor <|.. ReasoningStep
    StepExecutor <|.. CallableStep
    StepExecutor <|.. FanOutStep
    StepExecutor <|.. FanInStep
    DelegationStrategy <|.. RoundRobinStrategy
    DelegationStrategy <|.. CapabilityStrategy
    CompressionStrategy <|.. TruncationStrategy
    CompressionStrategy <|.. SummarizationStrategy
    CompressionStrategy <|.. MapReduceStrategy
    MemoryStore <|.. InMemoryStore
    MemoryStore <|.. FileStore
    ValidationRule <|.. RegexRule
    ValidationRule <|.. FormatRule
    ValidationRule <|.. RangeRule
    ValidationRule <|.. EnumRule
    ValidationRule <|.. CustomRule
    QueueConsumer <|.. KafkaAgentConsumer
    QueueConsumer <|.. RabbitMQAgentConsumer
    QueueConsumer <|.. RedisAgentConsumer
    QueueProducer <|.. KafkaAgentProducer
    QueueProducer <|.. RabbitMQAgentProducer
    QueueProducer <|.. RedisAgentProducer
    EmbeddingProtocol <|.. BaseEmbedder
    VectorStoreProtocol <|.. BaseVectorStore

• Agents — FireflyAgent wraps pydantic_ai.Agent with metadata, lifecycle hooks, and automatic registration. AgentRegistry provides singleton name-based discovery. DelegationRouter routes prompts across agent pools via RoundRobinStrategy or CapabilityStrategy. The @firefly_agent decorator defines an agent in one statement. Five template factories (create_summarizer_agent, create_classifier_agent, create_extractor_agent, create_conversational_agent, create_router_agent) cover common use cases out of the box.

• Tools — ToolProtocol (duck-typed) and BaseTool (inheritance) let you choose your extensibility style. ToolBuilder provides a fluent API for building tools without subclassing. Five guard types (ValidationGuard, RateLimitGuard, ApprovalGuard, SandboxGuard, CompositeGuard) intercept calls before execution. Three composition patterns (SequentialComposer, FallbackComposer, ConditionalComposer) build higher-order tools. ToolKit groups tools for bulk registration. Nine built-in tools (calculator, datetime, filesystem, HTTP, JSON, search, shell, text, database) are ready to attach to any agent.

• Prompts — PromptTemplate renders Jinja2 templates with variable validation and token estimation. PromptRegistry maps names to versioned templates. Three composers (SequentialComposer, ConditionalComposer, MergeComposer) combine templates at render time. PromptValidator enforces token limits and required sections. PromptLoader loads templates from strings, files, or entire directories.

• Reasoning — Six pluggable patterns implement AbstractReasoningPattern's template-method loop (_reason → _act → _observe → _should_continue): ReAct (observe-think-act), Chain of Thought (step-by-step), Plan-and-Execute (goal → plan → steps with optional replanning), Reflexion (execute → critique → retry), Tree of Thoughts (branch → evaluate → select), and Goal Decomposition (goal → phases → tasks). All produce structured ReasoningResult with ReasoningTrace. Prompts are slot-overridable. OutputReviewer can validate final outputs. ReasoningPipeline chains patterns sequentially.

• Content — TextChunker splits by tokens, sentences, or paragraphs with configurable overlap. DocumentSplitter detects page breaks and section separators. ImageTiler computes tile coordinates for VLM processing. BatchProcessor runs chunks through an agent concurrently with a semaphore. ContextCompressor delegates to pluggable strategies (TruncationStrategy, SummarizationStrategy, MapReduceStrategy). SlidingWindowManager maintains a rolling token-budgeted context window.

• Memory — ConversationMemory stores per-conversation turn history with token-budget enforcement (newest-first FIFO eviction). WorkingMemory provides a scoped key-value scratchpad backed by MemoryStore (InMemoryStore or FileStore). MemoryManager composes both behind a unified API and supports fork() for isolating working memory in delegated agents or pipeline branches while sharing conversation context.

• Validation — Five composable rules (RegexRule, FormatRule, RangeRule, EnumRule, CustomRule) feed into FieldValidator and OutputValidator. OutputReviewer wraps agent calls with parse-then-validate retry logic: on failure it builds a feedback prompt and retries up to N times. QoS guards (ConfidenceScorer, ConsistencyChecker, GroundingChecker) detect hallucinations and low-quality extractions before they propagate downstream.

• Pipeline — DAG holds DAGNode and DAGEdge objects with cycle detection and topological sort. PipelineEngine executes nodes level-by-level via asyncio.gather for maximum concurrency, with per-node condition gates, retries, and timeouts. PipelineBuilder offers a fluent API (add_node / add_edge / chain). Five step types (AgentStep, ReasoningStep, CallableStep, FanOutStep, FanInStep) adapt agents, patterns, and functions to DAG nodes.

• Observability — FireflyTracer creates OpenTelemetry spans scoped to agents, tools, and reasoning steps. FireflyMetrics records tokens (total, prompt, completion), latency, cost, errors, and reasoning depth via the OTel metrics API. FireflyEvents emits structured log records. @traced and @metered decorators instrument any function with one line. configure_exporters sets up OTLP or console exporters. UsageTracker automatically records token usage, cost estimates, and latency for every agent run, reasoning step, and pipeline execution. CostCalculator supports a built-in static price table and optional genai-prices integration. Budget enforcement logs warnings when configurable thresholds are exceeded.

• Explainability — TraceRecorder captures every LLM call, tool invocation, and reasoning step as DecisionRecord objects. ExplanationGenerator turns records into human-readable narratives. AuditTrail provides an append-only, immutable log with JSON export for compliance. ReportBuilder produces Markdown and JSON reports with statistics.

• Experiments — Experiment defines variants with model, temperature, and prompt overrides. ExperimentRunner executes all variants against a dataset. ExperimentTracker persists results with optional JSON export. VariantComparator computes latency, output length, and comparison summaries.

• Lab — LabSession manages interactive agent sessions with history. Benchmark runs agents against standardised inputs and reports p95 latency. EvalOrchestrator scores agent outputs with pluggable Scorer functions. EvalDataset loads/saves test cases from JSON. ModelComparison runs the same prompts across multiple agents for side-by-side analysis.

• Exposure — create_agentic_app() produces a FastAPI application with auto-generated POST /agents/{name}/run endpoints, SSE streaming via sse_stream, health/readiness/liveness checks, CORS and request-ID middleware, and multimodal input support. Queue consumers (KafkaAgentConsumer, RabbitMQAgentConsumer, RedisAgentConsumer) route messages to agents. Queue producers (KafkaAgentProducer, RabbitMQAgentProducer, RedisAgentProducer) publish results back. QueueRouter provides pattern-based message routing across agents.

• Embeddings — EmbeddingProtocol (duck-typed) and BaseEmbedder (inheritance with auto-batching) provide provider-agnostic text embedding. Eight providers ship out of the box: OpenAI, Azure OpenAI, Cohere, Google, Mistral, Voyage AI, AWS Bedrock, and Ollama (local). EmbedderRegistry manages named instances. Built-in similarity utilities (cosine_similarity, euclidean_distance, dot_product) compare vectors without external dependencies. Configuration via embedding_batch_size, embedding_max_retries, and default_embedding_model.

• Vector Stores — VectorStoreProtocol and BaseVectorStore provide pluggable storage and retrieval with four backends: InMemoryVectorStore (zero-dependency, brute-force cosine), ChromaDB, Pinecone, and Qdrant. Auto-embedding upserts documents without pre-computed vectors. search_text embeds a query string and searches in one call. Namespace scoping isolates document collections. VectorStoreRegistry manages named instances. EmbeddingStep and RetrievalStep integrate directly into DAG pipelines for RAG workflows.

• Studio — moved to its own repository: fireflyframework-agentic-studio. A browser-based visual IDE for building agent pipelines (drag-and-drop canvas, code generation, AI assistant, time-travel debugging). Install with pip install fireflyframework-agentic-studio and launch with firefly studio.

Runtime:

• Python 3.13 or later
• Git for cloning the repository
• UV package manager (recommended) or pip

Core dependencies (installed automatically):

• pydantic-ai >=1.56.0 — Agent engine (model calls, tool dispatch, streaming)
• pydantic >=2.10.0 — Data validation and settings
• pydantic-settings >=2.7.0 — Environment-based configuration
• Jinja2 >=3.1.0 — Prompt template engine
• OpenTelemetry API >=1.29.0 — Tracing and metrics
• OpenTelemetry SDK >=1.29.0 — Telemetry exporters

Optional dependencies (installed via extras):

• [rest] — FastAPI >=0.115.0, Uvicorn >=0.34.0, sse-starlette >=2.0.0
• [kafka] — aiokafka >=0.12.0
• [rabbitmq] — aio-pika >=9.5.0
• [redis] — redis-py >=5.2.0
• [costs] — genai-prices for up-to-date LLM pricing data
• [queues] — All queue backends (Kafka + RabbitMQ + Redis)
• [openai-embeddings] — openai >=1.0.0 for OpenAI/Azure embeddings
• [vectorstores-chroma] — chromadb >=0.5.0
• [vectorstores-pinecone] — pinecone >=5.0.0
• [vectorstores-qdrant] — qdrant-client >=1.12.0
• [all] — Everything (REST + queues + embeddings + vector stores + costs + security + HTTP)

LLM provider keys (at least one):

• OPENAI_API_KEY for OpenAI models
• ANTHROPIC_API_KEY for Anthropic models
• GEMINI_API_KEY for Google Gemini models
• GROQ_API_KEY for Groq models
• Or any Pydantic AI-supported provider

The interactive installer detects your platform, checks Python and UV, lets you choose extras, and installs everything with progress indicators and verification.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/fireflyframework/fireflyframework-agentic/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/fireflyframework/fireflyframework-agentic/main/install.ps1 | iex

Both installers support non-interactive mode for CI/CD:

# macOS / Linux — install with all extras, no prompts
curl -fsSL https://raw.githubusercontent.com/fireflyframework/fireflyframework-agentic/main/install.sh | bash

# Windows — install with all extras, no prompts
.\install.ps1 -NonInteractive -Extras all

git clone https://github.com/fireflyframework/fireflyframework-agentic.git
cd fireflyframework-agentic
uv sync --all-extras # or: pip install -e ".[all]"

python -c "import fireflyframework_agentic; print(fireflyframework_agentic.__version__)"
# 26.02.07

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/fireflyframework/fireflyframework-agentic/main/uninstall.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/fireflyframework/fireflyframework-agentic/main/uninstall.ps1 | iex

Or manually remove the cloned directory and its virtual environment.

Create a .env file (or set environment variables):

# Provider API key (Pydantic AI reads these automatically)
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=...
# GROQ_API_KEY=gsk_...

# Framework settings
FIREFLY_AGENTIC_DEFAULT_MODEL=openai:gpt-4o
FIREFLY_AGENTIC_DEFAULT_TEMPERATURE=0.3

The model string format is "provider:model_name" — e.g. "openai:gpt-4o", "anthropic:claude-sonnet-4-20250514", "google:gemini-2.0-flash". Pydantic AI resolves the matching API key from environment variables automatically. For programmatic credential management (Azure, Bedrock, custom endpoints), pass a Pydantic AI Model object directly to FireflyAgent(model=...) — see the tutorial.

from fireflyframework_agentic.agents import firefly_agent

@firefly_agent(name="assistant", model="openai:gpt-4o")
def assistant_instructions(ctx):
    return "You are a helpful conversational assistant."

from fireflyframework_agentic.tools import firefly_tool

@firefly_tool(name="lookup", description="Look up a term")
async def lookup(query: str) -> str:
    return f"Result for {query}"

from fireflyframework_agentic.agents import FireflyAgent
from fireflyframework_agentic.memory import MemoryManager

memory = MemoryManager(max_conversation_tokens=32_000)
agent = FireflyAgent(name="bot", model="openai:gpt-4o", memory=memory)

cid = memory.new_conversation()
result = await agent.run("Hello!", conversation_id=cid)
result = await agent.run("What did I just say?", conversation_id=cid)

from fireflyframework_agentic.reasoning import ReActPattern

react = ReActPattern(max_steps=5)
result = await react.execute(agent, "What is the weather in London?")
print(result.output)

from pydantic import BaseModel
from fireflyframework_agentic.validation import OutputReviewer

class Answer(BaseModel):
    answer: str
    confidence: float

reviewer = OutputReviewer(output_type=Answer, max_retries=2)
result = await reviewer.review(agent, "What is 2+2?")
print(result.output) # Answer(answer="4", confidence=0.99)

from fireflyframework_agentic.pipeline.builder import PipelineBuilder
from fireflyframework_agentic.pipeline.steps import AgentStep, CallableStep

pipeline = (
    PipelineBuilder("my-pipeline")
    .add_node("classify", AgentStep(classifier_agent))
    .add_node("extract", AgentStep(extractor_agent))
    .add_node("validate", CallableStep(validate_fn))
    .chain("classify", "extract", "validate")
    .build()
)
result = await pipeline.run(inputs="Process this document")

from fireflyframework_agentic.embeddings.providers import OpenAIEmbedder
from fireflyframework_agentic.vectorstores import InMemoryVectorStore, VectorDocument

embedder = OpenAIEmbedder(model="text-embedding-3-small")
store = InMemoryVectorStore(embedder=embedder)

# Upsert documents (auto-embedded)
await store.upsert([
    VectorDocument(id="1", text="Python is great for AI"),
    VectorDocument(id="2", text="Rust is fast and safe"),
])

# Search by text
results = await store.search_text("machine learning languages", top_k=1)
print(results[0].document.text)  # Python is great for AI

from fireflyframework_agentic.exposure.rest import create_agentic_app

app = create_agentic_app(title="My GenAI Service")
# uvicorn myapp:app --reload

from fireflyframework_agentic.exposure.queues.kafka import KafkaAgentConsumer

consumer = KafkaAgentConsumer("assistant", topic="requests", bootstrap_servers="localhost:9092")
await consumer.start()

from fireflyframework_agentic.exposure.queues.kafka import KafkaAgentProducer

producer = KafkaAgentProducer(topic="results", bootstrap_servers="localhost:9092")
await producer.publish({"agent": "assistant", "output": "Done processing."})
await producer.close()

firefly-agentic works seamlessly in Jupyter notebooks and JupyterLab. Since the framework is async-first, use await directly in notebook cells (Jupyter provides a running event loop automatically).

# From your clone directory
cd fireflyframework-agentic
source .venv/bin/activate # activate the venv created by the installer
pip install ipykernel # install Jupyter kernel support
python -m ipykernel install --user --name fireflyagentic --display-name "Firefly Agentic"
jupyter lab # or: jupyter notebook

Then select the Firefly Agentic kernel when creating a new notebook.

# Cell 1 — configure
import os
os.environ["OPENAI_API_KEY"] = "sk-..." # or set in .env
os.environ["FIREFLY_AGENTIC_DEFAULT_MODEL"] = "openai:gpt-4o"

# Cell 2 — create an agent
from fireflyframework_agentic.agents import FireflyAgent

agent = FireflyAgent(name="notebook-bot", model="openai:gpt-4o")
result = await agent.run("Explain quantum entanglement in two sentences.")
print(result.output)

# Cell 3 — use memory for multi-turn conversations
from fireflyframework_agentic.memory import MemoryManager

memory = MemoryManager(max_conversation_tokens=32_000)
agent_with_mem = FireflyAgent(name="chat", model="openai:gpt-4o", memory=memory)

cid = memory.new_conversation()
result = await agent_with_mem.run("My name is Alice.", conversation_id=cid)
print(result.output)

result = await agent_with_mem.run("What is my name?", conversation_id=cid)
print(result.output) # Alice

# Cell 4 — reasoning patterns
from fireflyframework_agentic.reasoning import ReActPattern

react = ReActPattern(max_steps=5)
result = await react.execute(agent, "What are the top 3 uses of Python in 2026?")
print(result.output)

# Cell 5 — structured output with validation
from pydantic import BaseModel
from fireflyframework_agentic.validation import OutputReviewer

class Summary(BaseModel):
    title: str
    bullet_points: list[str]
    confidence: float

reviewer = OutputReviewer(output_type=Summary, max_retries=2)
result = await reviewer.review(agent, "Summarize the benefits of async Python.")
result.output # displays the structured Summary object in the notebook

Tip: You do not need asyncio.run() or nest_asyncio in Jupyter — await works at the top level of any cell because Jupyter runs its own event loop.

docs/tutorial.md is a 20-chapter, hands-on guide that teaches every concept from zero to expert through a real-world Intelligent Document Processing pipeline. Start here if you want to learn the framework thoroughly.

docs/use-case-idp.md is a focused walkthrough of building a 7-phase IDP pipeline that ingests, splits, classifies, extracts, validates, assembles, and explains data from corporate documents — using agents, reasoning, document splitting, content processing, validation, explainability, pipelines, and REST exposure.

Detailed guides for each module:

• Architecture — Design principles and layer diagram
• Agents — Lifecycle, registry, delegation, decorators
• Template Agents — Summarizer, classifier, extractor, conversational, router
• Tools — Protocol, builder, guards, composition, built-ins
• Prompts — Templates, versioning, composition, validation
• Reasoning Patterns — 6 patterns, structured outputs, custom patterns
• Content — Chunking, compression, batch processing
• Memory — Conversation history, working memory, storage backends
• Validation — Rules, QoS guards, output reviewer
• Embeddings — 8 providers, auto-batching, similarity, registry
• Vector Stores — 4 backends, auto-embedding, search_text, namespaces
• Pipeline — DAG orchestrator, parallel execution, retries
• Observability — Tracing, metrics, events
• Explainability — Decision recording, audit trails, reports
• Experiments — A/B testing, variant comparison
• Lab — Benchmarks, datasets, evaluators
• Exposure REST — FastAPI integration, SSE streaming
• Exposure Queues — Kafka, RabbitMQ, Redis integration
• Studio — moved to fireflyframework-agentic-studio

git clone https://github.com/fireflyframework/fireflyframework-agentic.git
cd fireflyframework-agentic
uv sync --all-extras

uv run pytest # Run 1383+ tests
uv run ruff check src/ tests/ # Lint
uv run pyright src/ # Type check

Dev dependencies (installed with uv sync): pytest >=8.3.0, pytest-asyncio >=0.24.0, pytest-cov >=6.0.0, ruff >=0.9.0, pyright >=1.1.0, httpx >=0.28.0.

See CONTRIBUTING.md for guidelines.

See CHANGELOG.md for notable changes.

Apache License 2.0. See LICENSE for the full text.