Background wallpaper
← BackPRODUCTION

Agent State Machine

Hierarchical state machine with multi-tool integration and GraphRAG

•Updated October 16, 2025•2 min read
Tech Stack:
PythonMongoDBNeo4jFastAPI

Overview

Streamlined RinAI framework focused on hierarchical state machine architecture for complex multi-turn interactions. Features 6+ integrated tools (Twitter, crypto tracking, weather, NEAR Protocol) with GraphRAG memory system and Sub-50ms state transition latency for production workloads.

Clean, extensible architecture for building stateful AI agents with complex decision trees, optional Neo4j graph support, and simple web-based testing interface. MIT licensed for community use.

$state machine architecture

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ FastAPI │─────▶│ State FSM │─────▶│ Tool │ │ Server │ │ Manager │ │ Registry │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ MongoDB │ │ Neo4j │ │ Tools │ │ Memory │ │ (opt) │ │ (6+) │ └─────────┘ └─────────┘ └─────────┘

state_machine_example.py
from agent_state_machine import StateMachine, State, Transition

# Define states with handlers
idle = State("idle", on_enter=greet_user)
listening = State("listening", on_enter=process_input)
thinking = State("thinking", on_enter=select_tool)
responding = State("responding", on_enter=generate_response)

# Define transitions with guards
fsm = StateMachine([
    Transition(idle, listening, trigger="user_input"),
    Transition(listening, thinking, guard=has_tool_request),
    Transition(thinking, responding, trigger="tool_complete"),
    Transition(responding, idle, trigger="response_sent"),
])

# Tool integration example
@ToolRegistry.register("weather")
async def get_weather(location: str) -> dict:
    """Get current weather - automatically discovered by agent."""
    return {
        "location": location,
        "temperature": 72,
        "conditions": "Partly cloudy"
    }

Links: