# Agent Flows Documentation

Welcome to the Agent Flows Python library documentation. This library executes visual, no-code workflows from the RealTimeX desktop app.

## Getting Started

| If you want to... | Read... |
|-------------------|---------|
| Understand the codebase | [Project Structure](project-structure.md) |
| Learn the design | [Architecture Overview](architecture.md) |
| Configure the system | [Configuration Guide](configuration.md) |
| Use the public API | [API Reference](api-reference.md) |
| Validate flows with manifests | [Flow Testing Guide](testing.md) |
| Use variable templates | [Variable Interpolation](variable-interpolation.md) |

## Quick Reference

### Run a Flow

```python
from agent_flows import FlowExecutor

executor = FlowExecutor()
result = await executor.execute_flow(
    flow_id="your-flow-uuid",
    variables={"input": "value"}
)
```

### Run from Local File

```python
executor = FlowExecutor.from_file("path/to/flow.json")
result = await executor.execute_flow(variables={"name": "World"})
```

### Environment Variables

For a complete list of supported variables, see the **[Configuration Guide](configuration.md)**.

## Executor Reference

See [docs/executors/](executors/) for detailed documentation on each executor type:

- **api_call** - HTTP REST API requests
- **llm_instruction** - LLM-powered text generation
- **stream_ui** - UI component streaming
- **conditional** - If/else branching
- **switch** - Multi-case routing
- **loop** - Iterative execution
- **set_variables** - Variable assignment
- **flow_variables** - Variable initialization
- **finish** - Flow completion
- **web_scraping** - Web content extraction
- **web_search** - Search engine queries
- **mcp_server_action** - MCP tool invocation
- **run_command** - Shell command execution
- **code_interpreter** - Python code execution

## Development

### Run Tests

```bash
uv run pytest tests/unit/ -v
```

### Validate Imports

```bash
uv run python scripts/import_sweep.py --check-exports
```

### Check References

```bash
uv run python scripts/check_module_refs.py "module.path"
```
