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, GoogleVertexProvider, OpenAIProvider, OpenAIResponsesProvider)
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 LLMProvider, SystemMessage, TextBlock
from flowra.llm.providers.anthropic_vertex import AnthropicVertexProvider


async def main() -> None:
    async with AnthropicVertexProvider() as provider:
        config = ChatConfig(
            llm_config=LLMConfig(provider=provider, model="claude-sonnet-4-5@20250929"),
            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(user_message=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.75

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.75
File	Size	Uploaded
flowra-0.0.75.tar.gz	621.0 kB	Sep 18, 2026	Details

Built distribution (wheel)

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

Total release size: 772.4 kB

Release files / flowra-0.0.75.tar.gz

Download URL	flowra-0.0.75.tar.gz
Size	621.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`311bd5a78c71c02c10c0c55a13667e7cf93fd15adf3e7831c8dca3ff00356609`
BLAKE2b-256 checksum How to use checksums	`e548feab5399c0bab3264b7d3f257ddffdd782c3d48aa20131082532865e42d6`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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.75-py3-none-any.whl

Download URL	flowra-0.0.75-py3-none-any.whl
Size	151.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d02b6f8587541cb808370d7ef43d563aebc68ca37d1aacb8b00044c663b4c3f9`
BLAKE2b-256 checksum How to use checksums	`7ab6bb4765f1bb63c891b7f52aba637c10e9cf7f05eaa1f93e898bf392afa5aa`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}`