tantra

The agent actor runtime as a Python library. Install name tantra-harness, import name tantra.

Tantra gives each agent a durable FIFO inbox, an independent event journal, and one active turn. A process-wide Runtime owns providers, stores, tools, hooks, permissions, skills, memory, compaction, telemetry, actor tasks, and writer connections.

Install

The unrelated PyPI project tantra installs the same import name. Do not install both projects in one environment.

Basic usage

import asyncio
from uuid import uuid4

from tantra import Agent, OpenAICompatible, Runtime, SQLiteStore
from tantra.extratools.web import web_search


class Researcher(Agent):
    model = "gpt-5"
    prompt = "Answer with current, sourced information."
    tools = [web_search(api_key=BRAVE_API_KEY)]


async def main() -> None:
    store = SQLiteStore("sessions.db")
    await store.setup()
    runtime = Runtime(
        OpenAICompatible("https://api.openai.com/v1", OPENAI_API_KEY),
        store,
        [Researcher],
    )
    root_id = await runtime.create(Researcher)
    async with runtime.connect(root_id, writable=True) as connection:
        result = await connection.prompt(
            "What changed in Python 3.13?",
            command_id=uuid4(),
        )
    print(result.text)
    await runtime.aclose()


asyncio.run(main())

Connection.prompt() accepts a durable command and waits for its terminal result. For streaming, call send() and iterate the connection. Reconnect with the last scalar seq as after; use Runtime.events() for a child journal. Command IDs are UUIDs and make acceptance idempotent.

Subagents are independent actors. Models use the injected spawn, status, send, and finish tools; no parent stream merges child events. Plain completion leaves a child reusable and notifies its parent with status only, while finish delivers the final result. Human asks and approval-gated tools are root-only.

Compaction is opt-in with Runtime(compactor=PruneThenSummarize()). Configured runtimes budget the complete provider request, preserve system and tool definitions, and compact each actor independently.

For multi-process deployments, pair PostgresStore with the optional PostgresCoordinator for leased execution ownership, fenced writes, command forwarding, and takeover recovery. The default remains single-process.

Tantra 1.3 adds indexed command lookup, operational checkpoints, pooled PostgreSQL access, shared observer catch-up, and safe root-tree deletion with scoped cleanup and read-only dry runs. Runtime(history_mode="compacted") can load the latest summary and retained history; full history remains the default, and public replay stays complete. Stop PostgreSQL writers before upgrading an existing database.

See the documentation, the 1.3 upgrade guide, and the coordinator setup guide.

Reference app

apps/sarathi is the repository's interactive web application.

License

Apache-2.0