PyFlue 0.2.0: Bringing Flue's Agent Runtime Model to Python

PyFlue 0.2.0 is now available. This release is a major step toward parity with the TypeScript Flue framework and introduces a clearer runtime model for building production-oriented Python agents. The main theme of this release is structure. PyFlue now separates long-lived agents from finite workflows, adds persistent agent instances, introduces asynchronous dispatch, improves observability, and makes Pydantic AI the default harness backend.

PyFlue remains focused on Python teams that want framework-level ergonomics for agents while keeping access to the Python ecosystem, Pydantic models, Python deployment targets, and familiar server infrastructure.

Agents and Workflows

The largest change in PyFlue 0.2.0 is the adoption of the Flue agents and workflows architecture. An agent is a persistent, addressable runtime boundary. It is useful when you want one identity to keep working over time, such as a support assistant for a ticket, a coding assistant for a repository, or a chat assistant for a thread. A workflow is a finite unit of work. It runs once, produces a result, and has a workflow run id that can be inspected through run APIs and logs.

Python
from pyflue import create_agent

default = create_agent(
    lambda ctx: {
        "model": "openai/gpt-5.5",
        "instructions": f"Help with the request for instance {ctx.id}.",
    }
)

Python
from pyflue import FlueContext, create_agent

agent = create_agent(lambda ctx: {"model": "openai/gpt-5.5"})


async def run(ctx: FlueContext) -> dict:
    harness = await ctx.init(agent)
    session = await harness.session()
    response = await session.prompt(ctx.payload["text"])
    return {"summary": response.text}

This gives application authors a clearer way to choose the right abstraction. Use agents when identity and continuity matter. Use workflows when the unit of work is bounded and result-oriented.

Persistent Agent Instances

PyFlue agents are now addressable through stable instance ids.

HTTP
POST /agents/{name}/{id}

The {id} value identifies the continuing agent instance. It can represent a customer, repository, ticket, chat thread, or any other application-defined boundary.

Each instance can maintain separate sessions. This lets applications model long-running interaction without inventing their own session layer around the agent runtime.

Persistent agents can be used over HTTP, Server-Sent Events, and WebSocket connections. The Python client also includes agent helpers for invoking and connecting to deployed agents.

Asynchronous Dispatch

PyFlue 0.2.0 adds dispatch() for asynchronous agent input. This is useful when an application receives an event but should not keep the inbound request open while the model works. Common examples include webhooks, queue messages, issue comments, and chat events.

Python
from pyflue import dispatch
from src.agents.support_assistant import default as support_assistant


async def accept_comment(event):
    return await dispatch(
        support_assistant,
        id=event["customer_id"],
        session=event["case_id"],
        input={
            "type": "support.comment.created",
            "text": event["text"],
        },
    )

dispatch() returns a receipt once the input has been accepted. The agent processes the input through its own session and tools. For production systems, dispatch should be placed behind a durable application queue when accepted work must survive restarts. The current Python dispatch path uses process-memory admission, which is appropriate for local development and simple deployments, but not a replacement for durable message delivery.

Pydantic AI Is Now the Default Harness

PyFlue 0.2.0 makes Pydantic AI the default harness backend. This means a default PyFlue install now uses a typed, model-agnostic Python agent loop without requiring LangChain or LangGraph. DeepAgents remains supported, but it is now optional:

Shell
pip install "pyflue[deepagents]"

Then select it explicitly:

Python
agent = await init(harness="deepagents")

This change keeps the default dependency footprint smaller and better aligned with Python users who want Pydantic-first agent development.

Better Tooling and Customization

This release adds several improvements for defining agent behavior and capabilities.

Agent Profiles

Reusable profiles let teams share model-facing behavior across agents, workflows, and subagents.

Python
from pyflue import define_agent_profile

reviewer = define_agent_profile(
    {
        "name": "reviewer",
        "model": "anthropic/claude-sonnet-4-6",
        "instructions": "Review the change and report evidence-backed findings.",
    }
)

Profiles can define models, instructions, tools, skills, subagents, reasoning effort, and compaction behavior.

Subagent Profiles

Agents can now delegate focused work to declared subagent profiles. This supports patterns such as review agents, research agents, data analysis agents, and scoped coding assistants.

Packaged Skills

load_skill(path) imports an Agent Skills compatible SKILL.md file as a reusable skill object. This improves the path for packaging skills with applications rather than relying only on workspace-discovered skills.

Local Sandbox

The new host local() sandbox gives agents controlled access to the host filesystem and subprocess shell. This is useful in CI runners, local automation, and trusted environments where the host itself is the isolation boundary. Remote sandbox adapters remain available for Daytona, E2B, Modal, and Runloop.

WebSocket Support

PyFlue now supports WebSocket surfaces for both agents and workflows. Persistent agents can use WebSockets for multi-prompt sessions over one connection. Workflows can use WebSockets for one invocation that streams events and returns the final result.

Python
async with client.agents.connect("assistant", "thread-123") as conn:
    first = await conn.prompt("Summarize the context.")
    second = await conn.prompt("Draft a reply.")

Python
async with client.workflows.connect("summarize") as conn:
    messages = await conn.run({"text": "..."})

Observability and OpenTelemetry

PyFlue 0.2.0 adds a more complete event model and an OpenTelemetry adapter. Agent operations, workflow runs, model generations, tools, tasks, and compaction events can now be correlated through structured events. The OpenTelemetry adapter maps these events to spans, including model and token usage metadata.

Python
from pyflue import create_opentelemetry_observer, init

agent = await init(
    on_event=create_opentelemetry_observer(),
)

This makes it easier to inspect what agents are doing in production, including which operations ran, which tools were called, and how model usage accumulated.

Client Improvements

The Python client now mirrors more of the Flue SDK structure. It includes namespaces for agents, workflows, runs, and admin APIs. Persistent direct agent calls return result envelopes. Workflow invocations return run ids that can be inspected through run APIs. This distinction is important. Runs belong to workflows. Direct persistent agent prompts continue sessions and do not create workflow runs.

Improved Project Layout

New projects use the src/ layout by default:

Directory
AGENTS.md
pyflue.toml
.agents/
  roles/
  skills/
src/
  agents/
    assistant.py
  workflows/
    summarize.py

PyFlue still supports legacy file-based handlers, root-level agent files, and .pyflue or .agents locations, but src/agents and src/workflows are now the canonical layout.

Documentation and Parity Tracking

The release includes expanded documentation for agents, workflows, tools, subagents, models and providers, chat integrations, production guidance, observability, client usage, and Flue parity. A new parity reference page documents what PyFlue implements relative to the TypeScript Flue framework, what is intentionally not ported, and where Python-specific design choices differ. The main intentionally unported area is Cloudflare-specific runtime behavior, such as Durable Object backed execution recovery and Cloudflare-native runtime integration. PyFlue provides Python-native alternatives where practical, while keeping Cloudflare-specific internals out of the core Python runtime.

Breaking Changes

There are two important breaking changes in PyFlue 0.2.0.

Runs are now workflow-only. Direct and dispatched persistent agent prompts no longer create workflow runs or surface run ids. They correlate by agent instance, session, and operation.
DeepAgents is no longer the default harness and is no longer installed as a core dependency. Projects using DeepAgents should install the optional extra and select the backend explicitly.

Shell
pip install "pyflue[deepagents]"

Python
agent = await init(harness="deepagents")

Installing PyFlue 0.2.0

Install with pip:

Shell
pip install pyflue

Or with uv:

Shell
uv add pyflue

Optional extras include:

Shell
pip install "pyflue[deepagents]"
pip install "pyflue[otel]"
pip install "pyflue[sandboxes]"
pip install "pyflue[monty]"

Or use equivalent uv commands to add it to your projects.

Looking Ahead

PyFlue 0.2.0 establishes the framework shape for Python agents: persistent agents, finite workflows, typed outputs, skills, tools, sandboxes, observability, and deployment paths. The next areas to watch are production durability for dispatched input, deeper provider and model routing, and continued parity review against the TypeScript Flue framework. For now, this release gives Python teams a stronger foundation for building agent systems that are structured, observable, and easier to deploy.

Learn more about PyFlue on GitHub, read the PyFlue documentation, or visit the Flue framework website.

PyFlue 0.2.0: Bringing Flue's Agent Runtime Model to Python