flowagents 0.1.1
A zero-code AI workflow orchestration framework with state-driven agents
Requires Python: >=3.9
Keywords: agent, ai, anthropic, claude, framework, gpt, llm, multi-agent, openai, orchestration, state-machine, streaming, workflow, yaml, zero-code

# FlowAgents

[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.1-orange)](https://github.com/xiaoyu-work/flowagents)

**State-driven AI agent framework for task automation with human-in-the-loop.**

Build agents that collect information, validate input, and execute tasks with optional approval.

## Perfect For

- **Booking & Reservations** - Restaurants, flights, hotels, appointments
- **Request & Approval** - Leave requests, expense reports, access requests
- **Form Wizards** - Multi-step data collection with validation
- **Business Workflows** - Order processing, customer service, IT ticketing

## Installation

```bash
pip install flowagents              # Core
pip install flowagents[openai]      # + OpenAI
pip install flowagents[anthropic]   # + Claude
pip install flowagents[all]         # All providers
```

## Quick Example

```python
import asyncio
from flowagents import flowagent, StandardAgent, InputField, AgentStatus
from flowagents import Orchestrator, OpenAIClient

@flowagent(triggers=["book", "reservation"])
class BookingAgent(StandardAgent):
    guests = InputField("How many guests?")
    date = InputField("What date?")

    async def on_running(self, msg):
        return self.make_result(
            status=AgentStatus.COMPLETED,
            raw_message=f"Booked for {self.guests} on {self.date}!"
        )

async def main():
    llm = OpenAIClient(api_key="sk-xxx", model="gpt-4o-mini")
    orchestrator = Orchestrator(llm_client=llm)
    await orchestrator.initialize()

    result = await orchestrator.handle_message("user_1", "I want to book a table")
    print(result.raw_message)  # "How many guests?"

    result = await orchestrator.handle_message("user_1", "4")
    print(result.raw_message)  # "What date?"

    result = await orchestrator.handle_message("user_1", "Friday")
    print(result.raw_message)  # "Booked for 4 on Friday!"

asyncio.run(main())
```

## Key Features

- **State Machine** - `INITIALIZING → WAITING_FOR_INPUT → RUNNING → COMPLETED`
- **Field Collection** - Declarative `InputField` with validation
- **Approval Workflow** - Human confirmation before sensitive actions
- **Multi-LLM** - OpenAI, Claude, Azure, Gemini, Ollama, DashScope
- **Orchestrator** - Route messages to the right agent
- **Multi-tenant** - Built-in isolation for SaaS

## Documentation

- [**Getting Started**](docs/getting-started.md) - Build your first agent
- [**Full Documentation**](docs/index.md) - Complete guide
- [**Examples**](examples/) - Sample code

**Guides:** [Agents](docs/agents.md) | [Tools](docs/tools.md) | [LLM Providers](docs/llm-providers.md) | [Orchestrator](docs/orchestrator.md) | [Workflow](docs/workflow.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

[MIT](LICENSE)