Skip to main content
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-...",
)
VariableRequiredPurpose
FLOWX_OBSERVATORY_API_KEYYesAPI key from the Observatory Home page (scoped to organization + workspace).
FLOWX_OBSERVATORY_API_URLYesBase URL of your Observatory API.
FLOWX_OBSERVATORY_ORG_IDYesOrganization ID.
FLOWX_OBSERVATORY_WORKSPACE_IDYesWorkspace ID.
FLOWX_OBSERVATORY_APP_IDYesProject ID (maps to project_id).
OBSERVATORY_TRACINGNoSet 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

LayerDecoratorWhen 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.
Last modified on June 3, 2026