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

​
Apie (sync)

Use for scripts, Flask handlers, Celery tasks, and any synchronous code. 
from apie import Apie

apie = Apie.create({...})
apie.ready()  # blocks until registered

apie.with_run({...}, lambda run: ...)
apie.flush()
apie.shutdown()
Registration starts eagerly in __init__ when enabled. ready() blocks until complete.

​
AsyncApie (async)

Use for FastAPI, asyncio agents, and any async code. 
import asyncio
from apie import AsyncApie

async def main():
    apie = await AsyncApie.create({...})
    await apie.ready()  # must await

    await apie.with_run({...}, async_callback)
    await apie.flush()
    await apie.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 apie import with_openai_tool_call_async

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

​
Context propagation

Clientrun_contextAuto runId in MCP client?
Apie (sync)Sets contextvarsYes — create_instrumented_mcp_client reads context
AsyncApieDoes not set contextvarsNo — pass runId explicitly
With AsyncApie, 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 apie.tool_context({...}):
    # tool body

with apie.guard_context({...}):
    # guarded action
AsyncApie uses with_tool and with_guard (async callbacks) but not async context managers.

​
Blocking approval waits

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

​
Config with pre-built client

apie.config.py can export a pre-built instance: 
from apie import Apie

apie = Apie.create({...})

# Apie.create() with no args returns this instance if is_apie_client(apie)

​
Next steps

Connect your first agent

Setup with sync and async examples.

Instrumented MCP client

MCP context requirements.