PyFlue

PyFlue is the agent harness framework for Python. It gives you Markdown skills, stateful sessions, sandboxed filesystem and shell access, typed Pydantic outputs, streaming events, file-based webhook routes, and deployment-ready project structure.

PyFlue is inspired by the Flue framework and adapts the agent harness model for Python teams.

Warning: Active Development

PyFlue is under active development. The API may change. Pin your dependencies and review changelogs before updating.

Use it to build coding agents, issue triage agents, data analysis agents, support agents, and workflow agents that need controlled access to files, commands, tools, and structured outputs.

Install

With uv:

uv add pyflue

With pip:

pip install pyflue

Optional extras:

uv add "pyflue[monty]"
uv add "pyflue[sandboxes]"

pip install "pyflue[monty]"
pip install "pyflue[sandboxes]"

Quick Start

pyflue init my-agent
cd my-agent
pyflue run --prompt "Review this project"

Python API

from pydantic import BaseModel
from pyflue import init


class FixResult(BaseModel):
    fix_applied: bool
    summary: str


async def main():
    agent = await init(
        model="openai:gpt-5.5",
        sandbox="virtual",
        allow_write=True,
        allow_shell=True,
        allowed_commands=["git"],
    )
    session = await agent.session("fix-123")
    result = await session.skill(
        "triage",
        args={"issue_number": 123},
        result=FixResult,
    )
    if result.fix_applied:
        await session.shell("git status --short")

What PyFlue Gives You

Capability	What it means
Markdown skills	Put reusable workflows in .agents/skills/*.md.
Project instructions	Use AGENTS.md for global behavior and context.
Roles	Scope behavior with .agents/roles/*.md.
Sessions	Resume agent state with stable session IDs.
Tasks	Run focused child tasks with isolated history and shared sandbox.
Sandbox	Read, write, edit, grep, glob, and shell behind explicit policies.
Secret grants	Keep secrets out of prompts and grant them only per call.
Typed outputs	Validate results with Pydantic and repair invalid JSON automatically.
Streaming	Use session.stream(...), pyflue run --stream, or SSE.
Webhooks	Expose agents/*.py as /agents/{name}/{agent_id}.
Python code backend	Use pyflue[monty] for safe host-side Python snippets.
Remote sandboxes	Use Daytona, E2B, Modal, or Runloop with optional extras.
Connector guides	Use pyflue add to print agent-readable setup guides for sandbox providers.
Deployment	Generate Docker/FastAPI, CI, Railway, Render, Fly.io, Vercel, Netlify, and Cloudflare starter files.

Project Layout

AGENTS.md
pyflue.toml
.agents/
  roles/
    coder.md
  skills/
    triage.md
agents/
  default.py

File-Based Agent

triggers = {"webhook": True}


async def default(context):
    agent = await context.init()
    session = await agent.session(context.agent_id)
    result = await session.prompt(context.payload["prompt"])
    return {"text": result.text}

Run it locally:

pyflue dev --port 2024

Call it:

curl http://127.0.0.1:2024/agents/default/demo \
  -H "Content-Type: application/json" \
  -d '{"payload": {"prompt": "Review this repository"}}'

Streaming

pyflue run --stream --prompt "Review this project"

async for event in session.stream("Review this project"):
    print(event.type, event.data)

Connector Guides

List available guides:

pyflue add

Print a guide for a known sandbox provider:

pyflue add daytona --print

Start from any provider documentation URL:

pyflue add https://e2b.dev/docs --category sandbox --print | codex

Security Model

PyFlue starts with safe defaults:

• writes are disabled until allow_write=True
• shell execution is disabled until allow_shell=True
• compound shell syntax is blocked by default
• command allowlists are supported with allowed_commands
• secrets are not injected into prompts
• secrets are mounted into sandbox calls only when requested with secrets=[...]

Deployment

Generate deployment files:

pyflue build --target docker
pyflue build --target railway
pyflue build --target fly
pyflue build --target vercel
pyflue build --target netlify

Deploy with a supported provider CLI:

pyflue deploy --target fly

Development

uv sync --extra dev --extra docs
uv run --extra dev ruff check .
uv run --extra dev pytest
uv run --extra docs mkdocs build --strict
uv build