Python sync and async

When to use Ratri vs AsyncRatri, contextvar behavior, and async helper conventions.

Python ships two first-class clients. Pick based on your runtime — not on preference.

Ratri (sync)

Use for scripts, Flask handlers, Celery tasks, and any synchronous code.

from ratri import Ratri

ratri = Ratri.create({...})
ratri.ready()  # blocks until registered

ratri.with_run({...}, lambda run: ...)
ratri.flush()
ratri.shutdown()

Registration starts eagerly in __init__ when enabled. ready() blocks until complete.

AsyncRatri (async)

Use for FastAPI, asyncio agents, and any async code.

import asyncio
from ratri import AsyncRatri

async def main():
    ratri = await AsyncRatri.create({...})
    await ratri.ready()  # must await

    await ratri.with_run({...}, async_callback)
    await ratri.flush()
    await ratri.shutdown()

asyncio.run(main())

Registration runs as a background asyncio task. Always await ready() before instrumenting.

Async helper convention

Every integration helper has an *_async variant:

from ratri import with_openai_tool_call_async

await with_openai_tool_call_async(
    ratri,  # AsyncRatri instance
    {"runId": run.id, "toolName": "search"},
    async_callback,
)

Context propagation

Client	run_context	Auto runId in MCP client?
Ratri (sync)	Sets contextvars	Yes — create_instrumented_mcp_client reads context
AsyncRatri	Does not set contextvars	No — pass runId explicitly

With AsyncRatri, always pass runId to with_mcp_tool_call and create_instrumented_mcp_client_async. Do not rely on implicit context.

Context managers

Sync-only context managers:

with ratri.tool_context({...}):
    # tool body

with ratri.guard_context({...}):
    # guarded action

AsyncRatri uses with_tool and with_guard (async callbacks) but not async context managers.

Blocking approval waits

ratri.approvals.wait() blocks the calling thread (sync) or awaits (async). Set approval_timeout_ms appropriately for long-running agents.

Config with pre-built client

ratri.config.py can export a pre-built instance:

from ratri import Ratri

ratri = Ratri.create({...})

# Ratri.create() with no args returns this instance if is_ratri_client(ratri)

Next steps

Connect your first agent

Setup with sync and async examples.

Instrumented MCP client

MCP context requirements.