Python quickstart

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 (full list). Coming from belvedir-loop? See Migrating from Fractal.

1. Install the SDK

pip install belvedir

2. Initialize at process startup

Call initialize() once, before your agent makes LLM calls. There is no instrumentModules equivalent: auto-instrumentation sees the installed packages directly, so the only ordering rule is initialize() first. 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",
)

Raw requests / httpx calls to OpenAI-compatible endpoints (POST .../chat/completions) are captured too, streamed responses included; pass instrument_http=False to initialize() to opt out.

3. Wrap agent work in sessions

session links every span under one session id (required for tasks and task groups), 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

Call loop.flush() before a script or serverless handler returns, or pass disable_batch=True for local testing; see Flush on serverless.

5. Report outcomes

When your app knows whether a session actually worked, call loop.report_outcome(chat_id, "success" if order_shipped else "fail") after flush(); a "fail" keeps that session out of training data. Semantics and return values are on Outcomes. flush() and report_outcome() never raise; failures log warnings under the belvedir.loop logger.

Get started

Node SDK

Guides

Inference

Training

Benchmarks

Resources

Python quickstart

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