AI agents that run inside your application, under its rules.

pyfly agentic brings typed agents, tools, memory, retrieval, and workflows into your pyfly application. Configuration, dependency injection, lifecycle, and telemetry come from the framework.

Python 3.12+ · Native pyfly module · Pydantic AI
Scroll to explore

Capabilities

AI capabilities within your pyfly application.

Enable pyfly.agentic and inject AgentFactory into your services. Your application owns approval decisions, authentication, and access to business data.

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.

See the source

Delegation to specialists

A DelegationRouter strategy picks the agent for each prompt by capability, content, cost, or round robin. You can chain strategies or set fallbacks.

See the source

Tools from your code

@agent_tool turns an async function into a tool that runs its guards before each call. Pydantic AI toolsets pass through, MCP servers included.

See the source

Skills

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.

See the source

Human approval

A tool marked requires_approval pauses the run through Pydantic AI’s deferred tools. Your application collects the decision and resumes the agent.

See the source

Sandboxed scripts

With the agentic-script-execution extra, scripts run in Monty, with no file, network, or environment access. They reach only the functions you register.

See the source

Orchestration

Pipelines and workflows for agent work.

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

Stateful pipelines

Connect agents and functions around typed state. Routes, cycles, and parallel Send workers merge their updates through field reducers.

  • Timeouts and retries per node
  • Return Pause from a node to wait for input
  • Resume from a checkpoint once you attach a checkpointer
See the source

@workflow

Dynamic workflows

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.

  • A run budget for agents, tokens, and cost
  • human() pauses the run for input
  • A call journal, in memory unless you attach a backend
See the source

Context

Knowledge, memory, and review.

Each stage from a source document to model context is a piece you can inspect or replace. Providers and stores install as optional extras.

  1. Normalize

    PDFs, images, Office files, archives, and email become artifacts that record their origin. Office files need a converter you configure.

    See the source
  2. Chunk

    Split text, or chunk Markdown by its headings and keep each section’s breadcrumb. A compressor shortens context that runs long.

    See the source
  3. Embed

    BaseEmbedder puts OpenAI, Azure OpenAI, Cohere, Google, Mistral, Voyage AI, Amazon Bedrock, and Ollama behind one batching interface.

    See the source
  4. Retrieve

    Search Chroma, SQLite-vec, Pinecone, Qdrant, pgvector, or memory. Wrap any store to confine it to a tenant and workspace.

    See the source

Conversation memory

ConversationMemory wraps Pydantic AI’s message history with a token budget and summaries of older turns. Conversations live in process until you export them.

See the source

Working memory

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 source

Reasoning patterns

ReAct, Reflexion, plan and execute, tree of thoughts, goal decomposition, and chain of thought each run with the agent you pass in.

See the source

Output review

OutputReviewer retries an output that fails its schema or its rules. Each retry tells the model what failed.

See the source

Examples

Three examples, with their source.

An assistant calls Python tools, a classifier returns typed results, and a workflow asks for human review. Each excerpt links its complete source.

Give an assistant tools it can call

Your agent can look up application knowledge, check the time, or calculate a result. It chooses a tool and uses its response.

  • Typed Python functions and framework tools share the same agent.
  • Your application controls which tools the model can call.

Run this inside your configured Agentic runtime, then call await agent.run(...). The linked guide covers model setup and tool permissions.

docs/modules/agentic/agents.md
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],
)

Classify support requests into typed results

A classifier reads each customer message and returns a category, confidence, and explanation. Your service can route the request using those fields.

  • Pydantic validates the ClassificationResult returned by the model.
  • Confidence is a model estimate; your application sets escalation rules.

The complete example includes imports, sample requests, and model setup. Set PYFLY_AGENTIC_DEFAULT_MODEL and the selected provider’s credentials.

examples/agentic/classifier.py
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")

Ask a person to review an agent’s reply

The agent drafts a support reply. human() pauses the workflow so a person can accept it or request a revision.

  • The draft comes from the model; the review decision comes from a person.
  • The journal retains completed agent results while you collect a human decision.

The linked guide includes runner setup and resumption. Add a persistent journal backend to recover approvals after a restart.

docs/modules/agentic/workflows.md
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

Run agents like the rest of your service.

Agentic uses pyfly’s application lifecycle and telemetry. Configure exporters once for the service and its agents.

Application-scoped runtime

AgenticRuntime owns registries, budgets, and managed resources. pyfly injects AgentFactory and closes the runtime when the application stops.

See the source

Cost budgets

Budgets account for priced model usage within a runtime. In-flight calls can exceed a cap; strict cost mode rejects unknown prices.

See the source

Model routing

Pass SmartRoutingRunner to a workflow to pick the cheapest capable model for each call. A transient error moves the call up a tier.

See the source

Input and output guards

Attach PromptGuardMiddleware to screen prompts for injection and OutputGuardMiddleware to scan responses. Your service’s access controls still apply.

See the source

Runtime admin inventory

Admin lists registered agents, tools, and workflow definitions under its configured access policy. Prompts, credentials, model settings, and tool arguments stay private.

See the source

Usage and quotas

Inspect token totals, cost estimates, latency, retained calls, and quota limits. Totals reflect retention; models without pricing can show zero cost.

See the source

Java bridge

Call agents from Java services.

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.

Reactive Java client

AgenticClient returns single responses as a Reactor Mono and event streams as a Flux.

See the source

HTTP calls and streamed events

The REST transport sends agent requests and decodes server-sent events, with response timeouts, retries, and authentication headers.

See the source

Setup

Enable Agentic in your pyfly application.

Use Python 3.12 or 3.13 and the pyfly v26.10.11 release.

  1. Install the Agentic extra

    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 guide
  2. Enable the module

    Set 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-luna
    Read the installation guide
  3. Verify the installed module

    Check 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 guide

First agent and native runtime

Create typed agents and tools, then inject them into application services.

Read the native guide

The example collection

Worked examples cover tool calling, classification, memory, reasoning, and streaming.

Browse the examples

Lumen’s Agentic chapters

English and Spanish manuscripts extend the wallet example with agents, knowledge, workflows, and operations.

Read the book chapters
Sources and attribution

Copyright 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

Add an agent to your application.

Follow the native runtime guide to configure a model, inject an agent factory, and manage its lifecycle.