SDK overview

The Observatory SDK is the bridge between your code and the Observatory platform. Decorate your agents, chains, and tools; the SDK captures inputs, outputs, timings, token usage, and cost, then ships events to /api/report in the background.

Install

pip install flx-observatory-lib

The distribution is named flx-observatory-lib; the import name is flowxobservatory. Optional extras pull in framework integrations — for example pip install flx-observatory-lib[langchain] or flx-observatory-lib[openai]. Python 3.12 or newer is required.

Configure

Call configure() once at startup, or set the equivalent environment variables — the SDK reads them on import.

from flowxobservatory import configure

configure(
    org_id="your-org-id",
    workspace_id="your-workspace-id",
    project_id="your-project-id",
    api_url="https://your-observatory.example.com",
    api_key="FX-...",
)

Variable	Required	Purpose
`FLOWX_OBSERVATORY_API_KEY`	Yes	API key from the Observatory Home page (scoped to organization + workspace).
`FLOWX_OBSERVATORY_API_URL`	Yes	Base URL of your Observatory API.
`FLOWX_OBSERVATORY_ORG_ID`	Yes	Organization ID.
`FLOWX_OBSERVATORY_WORKSPACE_ID`	Yes	Workspace ID.
`FLOWX_OBSERVATORY_APP_ID`	Yes	Project ID (maps to `project_id`).
`OBSERVATORY_TRACING`	No	Set to `false` to turn off instrumentation without removing decorators.

export FLOWX_OBSERVATORY_API_KEY="FX-..."
export FLOWX_OBSERVATORY_API_URL="https://your-observatory.example.com"
export FLOWX_OBSERVATORY_ORG_ID="..."
export FLOWX_OBSERVATORY_WORKSPACE_ID="..."
export FLOWX_OBSERVATORY_APP_ID="..."

Don’t ship the API key in source control. Use your platform’s secret manager.

How the SDK works

Calls into decorated functions emit *_start and *_end events through track_event.
The event queue is in-memory and non-blocking — your hot path is not on the critical send path.
A background consumer flushes batches to /api/report on a short interval.
Delivery is best-effort: if a batch fails to send, those events are dropped rather than blocking your app.

Where instrumentation belongs

Layer	Decorator	When to use
Agent	`@agent("name")`	The top-level function that handles one user request.
Chain	`@chain("name")`	A sub-step inside the agent — retrieval, planning, formatting.
Tool	`@tool("name")`	A unit of external work — DB query, REST call, file fetch.

Use them like Russian dolls. Each level nests under the previous one, producing the chain-of-calls visible in Traces.

from flowxobservatory import agent, chain, tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)

@chain("extract-claim-data")
def extract(payload):
    holder = lookup_policy_holder(payload["policy_id"])
    return {"holder": holder, "claim": payload["claim"]}

@agent("claims-approval")
def run(ctx, payload):
    data = extract(payload)
    return decide(data)

LangChain and LangGraph

The SDK ships a callback handler that auto-captures LangChain’s on_*_start / on_*_end hooks. Register it once and every chain, tool, and LLM call inside the LangChain runtime emits events without further decoration.

from flowxobservatory.integrations.langchain import FlowxObservatoryCallbackHandler
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(callbacks=[FlowxObservatoryCallbackHandler()])

LangGraph nodes are picked up through the same handler.

Where to go next

Decorators

Full reference for @agent, @chain, @tool.

Event reporting

The event protocol, custom events, and saved / chat semantics.

Get started

Observability

Governance

Compliance

ROI & value

SDK reference

Setup

SDK overview

Install

Configure

How the SDK works

Where instrumentation belongs

LangChain and LangGraph

Where to go next

Decorators

Event reporting

​Install

​Configure

​How the SDK works

​Where instrumentation belongs

​LangChain and LangGraph

​Where to go next

Decorators

Event reporting

Install

Configure

How the SDK works

Where instrumentation belongs

LangChain and LangGraph

Where to go next