Python SDK

Python agents use belvedir: the same concepts as the Node SDK, with context managers instead of callbacks. It auto-instruments the installed anthropic / openai / LangChain / LlamaIndex packages. (The legacy fractal-loop package still works but is deprecated.)

1. Install the SDK

pip install belvedir

2. Initialize at process startup

Call initialize() once, before your agent starts making LLM calls. Unlike Next.js there is no bundler in the way, so no instrumentModules equivalent is needed. A second initialize() call logs a warning and is ignored:

import os
import belvedir as loop

loop.initialize(
    api_key=os.environ["BELVEDIR_API_KEY"],
    app_name="my-agent",
)

On belvedir>=0.6.0, raw requests / httpx calls to OpenAI-compatible endpoints (POST .../chat/completions) are captured automatically too, streamed responses included, so agent frameworks with their own HTTP layer are traced without a client SDK. Don’t rewrite raw HTTP calls to a client SDK just for tracing; pass instrument_http=False to initialize() to opt out.

3. Wrap agent work in sessions

Same as the Node SDK: session links every span under one session id (required for tasks and training sets), and task() optionally marks task boundaries. Both are context managers, they work inside async def bodies, and session also accepts a metadata dict. with_session is an alias of session:

with loop.session(session_id=chat_id, user_id=user.id):
    with loop.task("send_email"):
        agent.run("email danny the report")

4. Flush before short-lived processes exit

Spans export in batches; scripts and serverless handlers can exit before the batch ships. Call loop.flush() before returning, or pass disable_batch=True to initialize() for local testing.

5. Report outcomes

When your app knows whether a session actually worked, report it. Reported outcomes beat Belvedir’s model-judged labels: a "fail" keeps every task in that session out of training data.

loop.flush()  # the session must have arrived first
loop.report_outcome(chat_id, "success" if order_shipped else "fail")

flush() and report_outcome() never raise; failures log warnings under the belvedir.loop logger. report_outcome returns False if Belvedir hasn’t ingested the session yet (flush first, then retry) or if the outcome is anything other than "success" or "fail".

Get Started

SDK

Guides

Inference

Training

Benchmarks

Resources

1. Install the SDK

2. Initialize at process startup

3. Wrap agent work in sessions

4. Flush before short-lived processes exit

5. Report outcomes

​1. Install the SDK

​2. Initialize at process startup

​3. Wrap agent work in sessions

​4. Flush before short-lived processes exit

​5. Report outcomes

1. Install the SDK

2. Initialize at process startup

3. Wrap agent work in sessions

4. Flush before short-lived processes exit

5. Report outcomes