RouteKitAI

A minimal, production-ready framework for building and orchestrating AI agents

Features • Quick Start • Documentation • Examples • Contributing

---

⚠️ Early stage: RouteKitAI is still in very early development. APIs may change, and some features are experimental. Use with caution in production.

RouteKitAI is a Python framework for building AI agents with graph-based orchestration, built-in tracing, and deterministic replay. Unlike other frameworks, RouteKitAI treats observability and testability as first-class features from day one.

✨ Features

🎯 Core Capabilities

• Graph-Native Orchestration: Define agent workflows as explicit graphs with clear control flow
• Automatic Tracing: Every execution produces a complete, immutable trace log
• Deterministic Replay: Reproduce any agent run exactly for testing and debugging
• Type-Safe APIs: Full type hints with mypy compliance
• Async-First: Built for modern Python async/await patterns
• Minimal API: Just 5 core primitives—no bloat

🛡️ Production Features

• Security Hooks: PII redaction, tool allow/deny lists, approval gates
• Memory Support: Episodic, retrieval, and vector memory backends
• Policy System: ReAct, Supervisor, Graph, and custom policies
• Error Handling: Comprehensive error types with context
• CLI Tools: Run, trace, replay, and test agents from the command line
• Trace Analysis: Metrics, timeline visualization, step-by-step debugging, and search

🚀 Quick Start

Installation

pip install RouteKitAI

For development with CLI tools:

pip install "RouteKitAI[dev]"

Basic Example

import asyncio
from routekitai import Agent
from routekitai.providers.local import FakeModel
from routekitai.core.tools import EchoTool

# Create a model
model = FakeModel(name="test")
model.add_response("Hello from routekitai!")

# Create an agent
agent = Agent(
    name="my_agent",
    model=model,
    tools=[EchoTool()]
)

# Run the agent
async def main():
    result = await agent.run("Hello!")
    print(result.output.content)
    print(f"Trace ID: {result.trace_id}")

asyncio.run(main())

Graph-Based Workflow

import asyncio
from routekitai import Agent
from routekitai.core.policies import GraphPolicy
from routekitai.graphs import Graph, GraphNode, GraphEdge, NodeType
from routekitai.providers.local import FakeModel
from routekitai.core.tools import EchoTool

# Create models and agents
model1 = FakeModel(name="model1")
model1.add_response("Processing input...")

model2 = FakeModel(name="model2")
model2.add_response("Finalizing result...")

agent1 = Agent(name="agent1", model=model1, tools=[EchoTool()])
agent2 = Agent(name="agent2", model=model2, tools=[])

# Define a graph: agent1 -> tool -> agent2
graph = Graph(
    name="example_graph",
    entry_node="start",
    exit_node="end",
    nodes=[
        GraphNode(
            id="start",
            type=NodeType.MODEL,
            agent_name="agent1",
            output_mapping={"output": "processed_input"},
        ),
        GraphNode(
            id="echo_tool",
            type=NodeType.TOOL,
            tool_name="echo",
            input_mapping={"processed_input": "message"},
            output_mapping={"result": "echo_result"},
        ),
        GraphNode(
            id="end",
            type=NodeType.MODEL,
            agent_name="agent2",
            input_mapping={"echo_result": "prompt"},
        ),
    ],
    edges=[
        GraphEdge(source="start", target="echo_tool"),
        GraphEdge(source="echo_tool", target="end"),
    ],
)

# Create agent with graph policy
agent = Agent(
    name="graph_agent",
    model=model1,
    policy=GraphPolicy(graph=graph)
)

# Run the agent
async def main():
    result = await agent.run("Process this task")
    print(result.output.content)

asyncio.run(main())

📚 Documentation

• Architecture Guide: Deep dive into RouteKitAI's design
• Security & Governance: Security features and best practices
• Full documentation: Architecture, security, and guides (Read the Docs)

🎓 Examples

Check out the examples/ directory for complete examples:

• Basic Agent / Hello RouteKit: Simple agent with tools
• Real agent with Anthropic: Live Claude agent with tool use (requires ANTHROPIC_API_KEY)
• Graph Orchestration / Graph Policy: Multi-agent workflows
• Supervisor Pattern / Supervisor Policy: Supervisor delegating to sub-agents
• ReAct / Plan–Execute / Function Calling, Plan–Execute, Function Calling: Policy examples
• Evaluation Harness: Testing agents with datasets

Run all examples: ./scripts/run_examples.sh (or bash scripts/run_examples.sh).

🛠️ CLI Commands

RouteKitAI provides a CLI (routekitai) for common operations:

# Run an agent script
routekitai run agent_script.py

# View a trace (multiple formats available)
routekitai trace <trace_id>                    # Table view (default)
routekitai trace <trace_id> --format timeline  # Timeline visualization
routekitai trace <trace_id> --format steps     # Step-by-step execution
routekitai trace <trace_id> --format json     # JSON output
routekitai trace <trace_id> --format raw      # Raw JSONL

# Analyze trace metrics
routekitai trace-analyze <trace_id>            # Performance metrics, token usage, costs

# Search traces
routekitai trace-search "error"                # Search all traces for "error"
routekitai trace-search "model" --trace-id abc # Search specific trace
routekitai trace-search "tool" --event-type tool_called  # Filter by event type

# Replay a trace
routekitai replay <trace_id> --agent my_agent

# Start web UI for trace visualization
routekitai serve                    # Start on default port 8080
routekitai serve --port 3000        # Custom port
routekitai serve --host 0.0.0.0     # Make accessible from network

# Run sanity checks
routekitai test-agent

🏗️ Core Primitives

RouteKitAI keeps it minimal with 5 core primitives:

1. Model: LLM interface abstraction
2. Message: Conversation message representation
3. Tool: Callable function/tool definition
4. Agent: Agent with model and tools
5. Runtime: Orchestration and execution engine

🧪 Development

Setup

# Clone the repository
git clone https://github.com/MedGhassen/RouteKitAI.git
cd RouteKitAI

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=routekitai --cov-report=html

# Run specific test file
pytest tests/test_runtime.py

Code Quality

# Type checking
mypy src/

# Linting
ruff check src/ tests/ examples/

# Format code
ruff format src/ tests/ examples/

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Requirements

Core (always installed):

• Python 3.11+
• Pydantic 2.x
• NumPy 1.24+
• httpx 0.24+

Optional extras:

Extra	Purpose
[dev]	CLI, tests, linting, type checking (pytest, mypy, ruff, rich, typer, safety, bandit)
[ui]	Web UI for traces: routekitai serve (FastAPI, Uvicorn)
[optional]	Vector memory, OpenAI adapter (sentence-transformers, faiss, openai, nest-asyncio)
[docs]	Build documentation locally (MkDocs, MkDocs Material)

Examples:

pip install "RouteKitAI[dev]"       # development + CLI
pip install "RouteKitAI[dev,ui]"    # + trace web UI
pip install "RouteKitAI[docs]"      # build docs: mkdocs build / mkdocs serve

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

RouteKitAI is inspired by the need for testable, observable AI agent frameworks. Special thanks to the open-source community for their contributions and feedback.

🔗 Links

• GitHub: https://github.com/MedGhassen/RouteKitAI
• Documentation: https://routekitai.readthedocs.io
• Issues: https://github.com/MedGhassen/RouteKitAI/issues

---

Made with ❤️ by the Mohamed Ghassen Brahim