Flowra

Flow infra for building stateful, persistent LLM agents with tool use, parallel execution, and crash recovery. Requires Python 3.12+.

Features

State machine agents — define agents as Agent[Spec, Result] classes with @step methods, a single entry point, and typed spec/result contracts
Persistent state — Scalar[T] and MutableList[T] with incremental dirty-tracking and pluggable storage (in-memory, file-based, or custom)
Tool integration — @tool decorator for local functions, MCP server support, DI into tool handlers, agents as tools for LLM-driven delegation
LLM abstraction — provider-agnostic LLMProvider interface with immutable message types and real-time streaming (ships AnthropicVertexProvider, AnthropicFoundryProvider, OpenAIProvider, AzureOpenAIProvider, OpenAIResponsesProvider, GoogleVertexProvider)
Agents as tools — @agent_tool decorator exposes an agent as a tool the LLM can call autonomously; sub-agent runs its own system prompt and tool loop
Cooperative interrupts — InterruptToken for graceful cancellation across the entire execution tree
Pre-built agents — ChatAgent (multi-turn chat with session history) and TurnAgent (single-turn LLM tool loop with hooks and caching)

Installation

# Base package (no LLM providers)
pip install flowra

# With specific providers
pip install flowra[anthropic]
pip install flowra[openai]
pip install flowra[google]

# All providers
pip install flowra[providers]

Quick start

import asyncio

from flowra.agent import AgentRuntime, InMemorySessionStorage
from flowra.lib import LLMConfig
from flowra.lib.chat import ChatAgent, ChatConfig, ChatResult, ChatSpec
from flowra.llm import SystemMessage, TextBlock
from flowra.llm.providers.openai import OpenAIProvider


async def main() -> None:
    async with OpenAIProvider(api_key="sk-...") as provider:
        config = ChatConfig(
            llm_config=LLMConfig(provider=provider, model="gpt-4o"),
            system=[SystemMessage(blocks=[TextBlock(text="You are a helpful assistant.")])],
        )

        runtime = AgentRuntime(
            agents={"chat": ChatAgent},
            storage=InMemorySessionStorage(),
            services={ChatConfig: config},
        )

        while True:
            user_input = input("You: ")
            if not user_input:
                break

            result = await runtime.run(agent=ChatAgent, spec=ChatSpec.text(user_input))

            if isinstance(result, ChatResult) and result.response:
                print(f"Assistant: {result.response}")


asyncio.run(main())

Package structure

flowra/
├── llm/        # LLM abstraction (messages, blocks, provider interface)
├── tools/      # Tool definition, registration, execution
├── agent/      # Agent framework + execution engine + persistence
└── lib/        # Pre-built agents (ChatAgent, TurnAgent, hooks, caching)

Documentation

Getting Started — from installation to a working chatbot with tools in 5 minutes
Working with LLMs — providers, streaming, structured output, caching, extended thinking
Tools — tool groups, MCP servers, service injection
Agents — custom agents, state machines, control flow, parallel execution
Patterns — multi-agent patterns: router, pipeline, race, fan-out
Observability — hooks, spans, MLflow and OTel integrations

Development

make deps      # install dependencies (uv sync)
make check     # lint + test
make chat      # run interactive console chat example

Metadata

Release files for flowra 0.0.76

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flowra 0.0.76
File	Size	Uploaded
flowra-0.0.76.tar.gz	649.4 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for flowra 0.0.76
File	Interpreter	ABI	Platform	Reset
flowra-0.0.76-py3-none-any.whl 159.1 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 808.6 kB

Release files / flowra-0.0.76.tar.gz

Download URL	flowra-0.0.76.tar.gz
Size	649.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`49a7db7c2ff40476fa4d457504a7fa02fcdcfe33a04e413faf49c75df1e90187`
BLAKE2b-256 checksum How to use checksums	`f34d6689766060aafd0fa3602084cf3f1c991f5482fbeb813cf3693a0b0f25e0`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / flowra-0.0.76-py3-none-any.whl

Download URL	flowra-0.0.76-py3-none-any.whl
Size	159.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9788511900a368f711048554f84880b8b13c02aec76737f1426d5e2627aa33f8`
BLAKE2b-256 checksum How to use checksums	`bd7aac80d2086db5e40fa00e2195629e899fb5074982e613d40d7cdf11496692`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`