> ## 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.

# SDK overview

> Install the Observatory Python SDK, configure the API key, and learn where instrumentation belongs.

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

```bash theme={"system"}
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.

```python theme={"system"}
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.          |

```bash theme={"system"}
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="..."
```

<Warning>
  Don't ship the API key in source control. Use your platform's secret manager.
</Warning>

***

## How the SDK works

```mermaid theme={"system"}
flowchart LR
    Code["Your code<br/>@agent / @chain / @tool"] --> Track[track_event]
    Track --> Queue["Event queue<br/>(in-memory)"]
    Queue --> Consumer["Background consumer<br/>(thread)"]
    Consumer --> API["POST /api/report<br/>(batched)"]
```

* 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](../observability/traces).

```python theme={"system"}
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.

```python theme={"system"}
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

<CardGroup cols={2}>
  <Card title="Decorators" icon="at" href="./decorators">
    Full reference for `@agent`, `@chain`, `@tool`.
  </Card>

  <Card title="Event reporting" icon="paper-plane" href="./event-reporting">
    The event protocol, custom events, and `saved` / `chat` semantics.
  </Card>
</CardGroup>