Agentic has moved to pyfly.

Active development continues in pyfly.agentic, the native, opt-in Agentic module in pyfly v26.10.08 (package version 26.10.8). Use Agent, AgentTool, @agent and @agent_tool. The old namespace and public names have no aliases.

$ python -m pip install "pyfly[agentic] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/download/v26.10.08/pyfly-26.10.8-py3-none-any.whl"

Install the released pyfly wheel with the agentic extra, then enable pyfly.agentic.enabled. Follow the migration checklist. This site and the standalone releases are retained as historical material.

Historical standalone reference

The guides, examples and API names below describe the former standalone distribution. Use the native pyfly documentation for current development.

Built on Pydantic AI 2 Typed extension contracts 6 reasoning patterns 8 embedding providers 6 vector stores Python 3.13+ type-checked Apache-2.0
Why a metaframework

Keep the engine.
Gain the architecture.

Pydantic AI gives you type-safe, model-agnostic agents. A production system needs more: orchestration, validation-and-retry, memory across turns, traces and budgets, experiments. Firefly Agentic supplies every one of those as a dedicated, swappable layer — so your business logic never couples to infrastructure.

  • Build with FireflyAgent, ToolKit, MemoryManager and ModelOptions.
  • Lifecycle hooks, registries, delegation, memory, reasoning, validation and pipelines wrap them — all optional, all composable.
  • Keep model selection in configuration; Firefly validates options against each provider. Native SDK integrations remain available.
FireflyAgent applies before-run middleware, loads memory, resolves options, calls Pydantic AI and records the result.
Open diagram at full size
Architecture

One application API, composable capabilities

Firefly agents, tools, memory and model options form the application boundary. Add reasoning, validation, experiments and orchestration as needed.

Firefly application APIs, optional capabilities and the Pydantic AI provider engine.
Open diagram at full size

Extend components through structural protocols or abstract base classes. Runtime-checkable protocols support instance checks; register or attach your implementation explicitly.

Selected structural protocols and abstract base classes for extending Firefly components.
Open diagram at full size
Models and APIs

Keep your agent. Choose your API.

Existing openai: and azure: selectors retain Chat Completions. Choose openai-responses: or azure-responses: explicitly for Responses. Firefly validates typed options against the selected model.

Model selection and ModelOptions resolve through Firefly to Chat Completions, Responses or another provider.
Open diagram at full size

Models and options · Migration guide · Visual guide

Five minutes in

Familiar Python, all the way down

Async-first, typed, and decorator-friendly. Set your provider key and FIREFLY_AGENTIC_DEFAULT_MODEL, then run these cells in a notebook. Select openai-responses:gpt-6-luna for reasoning with tools.

assistant.py
from fireflyframework_agentic.agents import FireflyAgent
from fireflyframework_agentic.models import ModelOptions
from fireflyframework_agentic.tools.builtins import CalculatorTool

agent = FireflyAgent(
    name="assistant", tools=[CalculatorTool()],
    model_options=ModelOptions(max_tokens=4096),
)
result = await agent.run("Calculate 15 percent of 240.")
print(result.output)
from fireflyframework_agentic.agents import FireflyAgent
from fireflyframework_agentic.memory import MemoryManager

memory = MemoryManager(max_conversation_tokens=32_000)
agent = FireflyAgent(name="bot", memory=memory)
cid = memory.new_conversation()
await agent.run("My name is Alice.", conversation_id=cid)
result = await agent.run("What's my name?", conversation_id=cid)
print(result.output)
from fireflyframework_agentic.agents import FireflyAgent
from fireflyframework_agentic.reasoning import ReActPattern

agent = FireflyAgent(name="reasoner")
react = ReActPattern(max_steps=5)
result = await react.execute(agent, "Explain bounded retries and backoff.")
print(result.output)
from fireflyframework_agentic.agents import FireflyAgent
from fireflyframework_agentic.pipeline import PipelineBuilder, AgentStep

summarizer = FireflyAgent(name="summarizer", instructions="Summarize in one sentence.")
editor = FireflyAgent(name="editor", instructions="Rewrite the summary clearly.")
pipeline = (
    PipelineBuilder("summarize-and-edit")
    .add_node("summarize", AgentStep(summarizer))
    .add_node("edit", AgentStep(editor))
    .chain("summarize", "edit").build()
)
result = await pipeline.run(inputs="Retries stop after three attempts.")
print(result.final_output)
Intelligence layer

Six reasoning patterns, one interface

Choose a strategy for your task. Patterns produce structured results and traces; branching and decomposition use their own execution paths.

Six reasoning patterns — ReAct, Chain of Thought, Plan-and-Execute, Reflexion, Tree of Thoughts, Goal Decomposition — with shared result types and distinct execution strategies.
Open diagram at full size
› ReAct › Chain of Thought › Plan-and-Execute › Reflexion › Tree of Thoughts › Goal Decomposition
Orchestration layer

Declarative DAGs & code-defined workflows

A typed pipeline graph for structure; a Python DSL with journal-based replay. Use either, or both.

Pipeline scheduling, conditional Send routing, Pause and explicit checkpoint-based resume.
Pipeline — declarative DAG · Open diagram at full size
Dynamic Workflows: the @workflow DSL primitives over a WorkflowContext carrying runner, journal, budget and routing, with verification helpers.
Workflows — code-defined DSL · Open diagram at full size
Retrieval-augmented generation

Bring your own embeddings & vector store

Eight embedding providers and six vector-store backends behind separate embedding and vector-store contracts — drop straight into a pipeline with EmbeddingStep and RetrievalStep.

Retrieval-augmented generation: eight embedding providers and six vector-store backends behind the EmbeddingProtocol and VectorStoreProtocol.
Open diagram at full size