Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 2, 2026