Ravi Agent Framework¶

You want to build an AI agent. Not a chatbot that wraps a single API call, but a real one — one that can call tools, remember what it said three conversations ago, wait for a human to approve a sensitive action, recover from crashes, and scale across workers when you need it to.

That is what Ravi is for.

The story in one picture¶

Every request follows the same path — from a client request, through the durable runtime queue, executing the ReAct loop, calling tools, and returning the result.

The key insight: the caller never holds a reference to the agent. It sends a message to an address (AgentId). The runtime delivers it. Whether the agent is in the same process, a remote gRPC node, or a Kubernetes pod does not change the call site.

Kernel Architecture¶

The kernel defines the core protocols, messages, tools, memory, and guardrails, all building upon a durable Runtime substrate:

Developer journey¶

1. Read Installation and run Quickstart — you will have a working agent in under ten minutes.
2. Understand why the actor model matters in Agent Lifecycle and Streaming and Events.
3. Extend the system with Create a Tool and Connect MCP Tools.
4. Read The Kernel when you are ready to understand the contracts everything is built on.
5. Move to the durable flow in First Durable Run and Local and Kind.
6. Use Observability and Runbook when debugging in production.

Installation¶

git clone https://github.com/Ravikumarchavva/ravi.git
cd ravi/ravi-engine
uv sync

# Notebook support
uv sync --group notebooks

# Browser automation (WebSurferTool)
uv sync --group browser

# S3 / object storage
uv sync --group storage

Your first agent¶

import asyncio
from ravi.config import settings
from ravi.agents import ReActAgent, Runtime
from ravi.agents.context import ContextConfig, InMemoryHistoryProvider
from ravi.integrations.llm import LLMFactory
from ravi.capabilities.tools import CalculatorTool


async def main() -> None:
    # 1. Initialize the LLM client
    model = LLMFactory(settings.CHAT_MODEL, settings.OPENAI_API_KEY).build()

    # 2. Construct the agent with custom capabilities and tools
    agent = ReActAgent(
        "helper",
        model=model,
        tools=[CalculatorTool()],
        context=ContextConfig(InMemoryHistoryProvider()),
        system_instructions="You are a helpful assistant.",
    )

    # 3. Start the runtime, register the agent, and run the interactive console
    async with Runtime() as rt:
        await rt.register(agent)

        # 4. Use the built-in Console REPL to talk to the agent
        from ravi.console import Console
        console = Console(agent, runtime=rt)
        await console.interactive(stream=True)


if __name__ == "__main__":
    asyncio.run(main())

The shape stays the same whether you add tools, guardrails, streaming, HITL approvals, or swap in a distributed runtime. The call site does not change — only the configuration does.

Architecture at a glance¶

Higher layers may import from lower ones. The reverse is never allowed. uv run lint-imports enforces this structural integrity in CI.

Features¶

• Actor-model agents — every agent has an address, receives messages, and communicates only through the runtime.
• Human-in-the-loop approvals and structured human input flows, pausable and resumable.
• Tool calling with JSON-schema validation, risk tiers, and MCP server integration.
• Async-first across agents, tools, memory, and every service boundary.
• Streaming responses and event-driven UI updates over SSE.
• Built-in observability: structured logs, OpenTelemetry traces, Grafana dashboards.
• Multiple deployment paths: local monolith, Docker Compose, and Kind/Kubernetes.
• Example notebooks covering foundations, memory, MCP tools, safety, runtime, and observability.

Examples¶

Explore the examples/ folder for notebooks covering everything from a single-tool agent to Kubernetes deployments.

For architecture deep-dives and the full kernel contract reference, see The Kernel and Layered Architecture.