Source: https://fireflyframework.org/agentic/
Language: en

pyfly agentic, the native Python AI module in pyfly

# 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.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-pyfly/docs/modules/agentic/) [See the examples](https://fireflyframework.org/agentic/#examples)

Python 3.12+ · Native pyfly module · Pydantic AI

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](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/agents)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/agents/delegation.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/tools/decorators.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/skills)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/agents/base.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/execution/monty_env.py)

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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/pipeline/builder.py)

`@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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/workflows/primitives.py)

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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/content/binary/normalizer.py)
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](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/content)
3. ### Embed

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

   [See the source](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/embeddings)
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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/vectorstores/scoped.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/memory/conversation.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/agentic/native-runtime.md#native-data-memory-and-transactions)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/reasoning)

### Output review

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

[See the source](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/validation/reviewer.py)

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

```python
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],
)
```

[View the full file](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/agentic/agents.md#L287-L297)

### 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

```python
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")
```

[View the full file](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/examples/agentic/classifier.py#L47-L67)

### 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

```python
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}")
```

[View the full file](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/agentic/workflows.md#L451-L459)

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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/auto_configuration.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/observability/budget.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/workflows/routing.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/agents/builtin_middleware.py)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/admin.md#agentic-application-runtime-only)

### 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](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/admin.md#agentic-application-runtime-only)

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](https://github.com/fireflyframework/fireflyframework-jafly/blob/5dc0b95bd3ff17b51f8d6d8565f14e26fdc005e8/fireflyframework-agentic-bridge-core/src/main/java/org/fireflyframework/agentic/bridge/AgenticClient.java)

### 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](https://github.com/fireflyframework/fireflyframework-jafly/blob/5dc0b95bd3ff17b51f8d6d8565f14e26fdc005e8/fireflyframework-agentic-bridge-core/src/main/java/org/fireflyframework/agentic/bridge/transport/rest/RestAgenticTransport.java)

[Read the bridge quick start](https://github.com/fireflyframework/fireflyframework-jafly/blob/5dc0b95bd3ff17b51f8d6d8565f14e26fdc005e8/docs/QUICK_START.md) [View the bridge source](https://github.com/fireflyframework/fireflyframework-jafly/tree/main/modules/agentic-bridge)

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](https://fireflyframework.github.io/fireflyframework-pyfly/docs/modules/agentic/getting-started/installation/)
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](https://fireflyframework.github.io/fireflyframework-pyfly/docs/modules/agentic/native-runtime/)
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](https://fireflyframework.github.io/fireflyframework-pyfly/docs/modules/agentic/native-runtime/)

Related

### Where to go after the first run.

#### First agent and native runtime

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

[Read the native guide](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/agentic/native-runtime.md)

#### The example collection

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

[Browse the examples](https://github.com/fireflyframework/fireflyframework-pyfly/tree/46919f58cca4f17521213248ae7f01f8a89953d1/examples/agentic)

#### Lumen’s Agentic chapters

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

[Read the book chapters](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/book/manuscript/19-agentic-agents.md)

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.

- [Stateful pipeline engine](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/pipeline/engine.py)
- [Dynamic workflow runtime](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/workflows/registry.py)
- [Embedding and retrieval pipeline steps](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/pipeline/steps.py)
- [Memory storage and conversation boundaries](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/src/pyfly/agentic/memory/manager.py)
- [Dependencies and optional integrations](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/pyproject.toml)
- [Apache-2.0](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/LICENSE)

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.

[Read the documentation](https://fireflyframework.github.io/fireflyframework-pyfly/docs/modules/agentic/) [View the source](https://github.com/fireflyframework/fireflyframework-pyfly/blob/46919f58cca4f17521213248ae7f01f8a89953d1/docs/modules/agentic/native-runtime.md)
