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.

This guide walks you from an empty Observatory to a live trace flowing in from your first agent. Plan on 10–15 minutes.

​
Prerequisites

  • An Observatory instance (managed cloud, or self-hosted)
  • Python 3.12 or newer
  • An LLM provider key (OpenAI, Anthropic, Google, or Ollama)
  • Permission to create projects in your Observatory organization and workspace

​
Steps

1

Create a project

Sign in to Observatory and open Projects. Click Add Project, give it a name, and confirm. Observatory creates the project and an API key in the same step.
2

Copy your API key

On the Home page, the API key panel shows the key for the selected organization and workspace. Click Copy and store the value as the FLOWX_OBSERVATORY_API_KEY environment variable in your app, alongside your organization, workspace, and project IDs.
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="..."
Treat the API key like a database password. Don’t commit it to source control.
3

Install the SDK

Add the SDK to your Python project:
pip install flx-observatory-lib
The distribution is flx-observatory-lib; you import it as flowxobservatory. The SDK ships an event queue and a background consumer that batches events to POST /api/report. You don’t need to manage the connection yourself.
4

Instrument an agent

Decorate the function that runs your agent with @agent. The SDK captures inputs, outputs, timings, and any nested chains or tool calls automatically.
from flowxobservatory import agent

@agent("claims-approval")
def run(ctx, payload):
    # your existing logic
    return decide(payload)
The string argument names the agent and is what appears in the Agent column on the LLM Calls page.
Inner LangChain or LangGraph chains are picked up automatically through the FlowxObservatoryCallbackHandler. You don’t need to instrument them by hand.
5

Run the agent and confirm traces

Invoke the agent once with realistic input. The SDK flushes events every few seconds.Open Observability → Traces in Observatory. Within ~30 seconds you should see the run, agent name, model, duration, and token count.
You see a row for your run with status success, the right agent name, and a non-zero duration.
6

Open the trace

Click the run. The detail drawer shows the full chain-of-calls — every LLM call, tool invocation, and event with inputs, outputs, latencies, and token usage.

​
Validate the rest of the platform

Once one trace lands, the rest of Observatory has data to work with:

Analytics

p50/p95 latency, cost by model, error rate.

Risk Dashboard

The 6-dimensional risk score updates automatically.

Compliance heatmap

Controls start evaluating against the new evidence.

ROI overview

Configure baselines to start producing ROI numbers.

​
Troubleshooting

  • Confirm FLOWX_OBSERVATORY_API_KEY is set in the environment your app actually reads from (not just your shell).
  • Check the app logs for flowxobservatory errors — connection refused usually means FLOWX_OBSERVATORY_API_URL points at the wrong host or is missing the scheme.
  • Confirm the project you’re looking at in the UI matches the API key you exported.
The function must be decorated with @agent("name") (not bare @agent). The string is what populates the Agent column.
Token counting requires the provider’s response metadata. If you’re calling a custom or proxied endpoint that strips usage fields, Observatory has nothing to count. See Event reporting for the rules.

SDK decorators

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

Observability overview

What you can do once traces are flowing.
Last modified on June 2, 2026