Typed agents
Agent wraps Pydantic AI with typed outputs, middleware, and a registry. Create it through an injected AgentFactory to bind it to your application’s runtime.
pyfly agentic brings typed agents, tools, memory, retrieval, and workflows into your pyfly application. Configuration, dependency injection, lifecycle, and telemetry come from the framework.
Capabilities
Enable pyfly.agentic and inject AgentFactory into your services. Your application owns approval decisions, authentication, and access to business data.
Agent wraps Pydantic AI with typed outputs, middleware, and a registry. Create it through an injected AgentFactory to bind it to your application’s runtime.
A DelegationRouter strategy picks the agent for each prompt by capability, content, cost, or round robin. You can chain strategies or set fallbacks.
@agent_tool turns an async function into a tool that runs its guards before each call. Pydantic AI toolsets pass through, MCP servers included.
A SKILL.md file in the Agent Skills layout holds instructions that join the system prompt, and its listed resources load only when the model asks.
A tool marked requires_approval pauses the run through Pydantic AI’s deferred tools. Your application collects the decision and resumes the agent.
With the agentic-script-execution extra, scripts run in Monty, with no file, network, or environment access. They reach only the functions you register.
Orchestration
Build a graph when the steps are known in advance, or write a Python function when they unfold as it runs. Both call agents and ordinary functions.
PipelineBuilder
Connect agents and functions around typed state. Routes, cycles, and parallel Send workers merge their updates through field reducers.
Pause from a node to wait for input@workflow
A workflow is an async Python function. It calls agents with agent(), fans out with parallel or map_agents, and combines results in plain Python.
human() pauses the run for inputContext
Each stage from a source document to model context is a piece you can inspect or replace. Providers and stores install as optional extras.
PDFs, images, Office files, archives, and email become artifacts that record their origin. Office files need a converter you configure.
See the sourceSplit text, or chunk Markdown by its headings and keep each section’s breadcrumb. A compressor shortens context that runs long.
See the sourceBaseEmbedder puts OpenAI, Azure OpenAI, Cohere, Google, Mistral, Voyage AI, Amazon Bedrock, and Ollama behind one batching interface.
Search Chroma, SQLite-vec, Pinecone, Qdrant, pgvector, or memory. Wrap any store to confine it to a tenant and workspace.
See the sourceConversationMemory wraps Pydantic AI’s message history with a token budget and summaries of older turns. Conversations live in process until you export them.
Async facts use pyfly Data’s relational or document resources and join its unit of work. File and in-memory stores remain available.
See the sourceReAct, Reflexion, plan and execute, tree of thoughts, goal decomposition, and chain of thought each run with the agent you pass in.
See the sourceOutputReviewer retries an output that fails its schema or its rules. Each retry tells the model what failed.
Examples
An assistant calls Python tools, a classifier returns typed results, and a workflow asks for human review. Each excerpt links its complete source.
Your agent can look up application knowledge, check the time, or calculate a result. It chooses a tool and uses its response.
Run this inside your configured Agentic runtime, then call await agent.run(...). The linked guide covers model setup and tool permissions.
from pyfly.agentic.agents import Agent
from pyfly.agentic.tools.builtins import DateTimeTool, CalculatorTool
async def custom_lookup(query: str) -> str:
glossary = {"retry": "Repeat a failed operation within a bounded attempt limit."}
return glossary.get(query.strip().lower(), "No glossary entry for that term.")
agent = Agent(
name="smart-assistant",
tools=[DateTimeTool(), CalculatorTool(), custom_lookup],
)A classifier reads each customer message and returns a category, confidence, and explanation. Your service can route the request using those fields.
ClassificationResult returned by the model.The complete example includes imports, sample requests, and model setup. Set PYFLY_AGENTIC_DEFAULT_MODEL and the selected provider’s credentials.
async def main() -> None:
agent = create_classifier_agent(
categories=["billing", "technical_support", "sales", "feedback"],
descriptions={
"billing": "Invoices, charges, payments, refunds",
"technical_support": "Bugs, how-to questions, password resets",
"sales": "Upgrades, new purchases, pricing inquiries",
"feedback": "Compliments, complaints, suggestions",
},
model=MODEL,
)
print("=== Text Classifier ===\n")
for text in SAMPLES:
result = await agent.run(text)
out = result.output
print(f"Text : {text}")
print(f"Category : {out.category}")
print(f"Confidence: {out.confidence:.2f}")
print(f"Reasoning : {out.reasoning}\n")The agent drafts a support reply. human() pauses the workflow so a person can accept it or request a revision.
The linked guide includes runner setup and resumption. Add a persistent journal backend to recover approvals after a restart.
from pyfly.agentic.workflows import workflow, agent, human, Journal, WorkflowInterrupt
@workflow(name="triage")
async def triage(args, ctx):
draft = await agent(f"draft a reply to: {args}")
decision = await human(f"Approve this reply?\n\n{draft}")
if decision.lower().startswith("y"):
return draft
return await agent(f"revise per feedback '{decision}': {draft}")Operations
Agentic uses pyfly’s application lifecycle and telemetry. Configure exporters once for the service and its agents.
AgenticRuntime owns registries, budgets, and managed resources. pyfly injects AgentFactory and closes the runtime when the application stops.
Budgets account for priced model usage within a runtime. In-flight calls can exceed a cap; strict cost mode rejects unknown prices.
See the sourcePass SmartRoutingRunner to a workflow to pick the cheapest capable model for each call. A transient error moves the call up a tier.
Attach PromptGuardMiddleware to screen prompts for injection and OutputGuardMiddleware to scan responses. Your service’s access controls still apply.
Admin lists registered agents, tools, and workflow definitions under its configured access policy. Prompts, credentials, model settings, and tool arguments stay private.
See the sourceInspect token totals, cost estimates, latency, retained calls, and quota limits. Totals reflect retention; models without pricing can show zero cost.
See the sourceJava bridge
Firefly Agentic Bridge is a Java client for an HTTP agent service. Your team hosts that service and builds it to the bridge’s contract.
AgenticClient returns single responses as a Reactor Mono and event streams as a Flux.
The REST transport sends agent requests and decodes server-sent events, with response timeouts, retries, and authentication headers.
See the sourceSetup
Use Python 3.12 or 3.13 and the pyfly v26.10.11 release.
Install the release wheel in your application’s virtual environment. Add namespaced integration extras when needed.
python -m pip install "pyfly[agentic] @ https://github.com/fireflyframework/fireflyframework-pyfly/releases/download/v26.10.11/pyfly-26.10.11-py3-none-any.whl" Read the installation guideSet pyfly.agentic.enabled in pyfly.yaml. Supply model credentials through your environment. Your services can inject AgentFactory.
pyfly: agentic: enabled: true default_model: openai-responses:gpt-6-lunaRead the installation guideCheck the installed imports, then follow the native guide for an offline agent and application setup.
python -c "from pyfly.agentic import AgentFactory, AgenticRuntime; print('pyfly agentic ready')"Read the installation guideCreate typed agents and tools, then inject them into application services.
Read the native guideWorked examples cover tool calling, classification, memory, reasoning, and streaming.
Browse the examplesEnglish and Spanish manuscripts extend the wallet example with agents, knowledge, workflows, and operations.
Read the book chaptersCopyright 2026 Firefly Software Foundation. Excerpts are selected from pyfly’s native Agentic documentation and examples. They replace the former standalone excerpts; linked files contain their imports and surrounding setup.
Next step
Follow the native runtime guide to configure a model, inject an agent factory, and manage its lifecycle.