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

# Getting started

> Connect your first project, instrument an agent, and see traces in Observatory in under 15 minutes.

> [!NOTE]
>
> **Observatory availability.** In FlowX.AI 6.0, Observatory runs on environments operated by FlowX. It isn't included in client deployments in this release.

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](https://docs.flowx.ai/6.x/observatory/setup/self-hosted.md))
* 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.

```bash theme={"dark"}
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]
>
> 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:

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

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

> [!TIP]
>
> 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.

> [!TIP]
>
> 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:

> [card] [Analytics](https://docs.flowx.ai/6.x/observatory/observability/analytics.md)
>
> p50/p95 latency, cost by model, error rate.

> [card] [Risk Dashboard](https://docs.flowx.ai/6.x/observatory/governance/risk-dashboard.md)
>
> The 6-dimensional risk score updates automatically.

> [card] [Compliance heatmap](https://docs.flowx.ai/6.x/observatory/compliance/gap-analysis-heatmap.md)
>
> Controls start evaluating against the new evidence.

> [card] [ROI overview](https://docs.flowx.ai/6.x/observatory/roi/overview.md)
>
> Configure baselines to start producing ROI numbers.

***

## Troubleshooting

> [accordion] No traces appear after 30 seconds
>
> * 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.

> [accordion] Traces show but the agent name is empty
>
> The function must be decorated with `@agent("name")` (not bare `@agent`). The string is what populates the **Agent** column.

> [accordion] Token counts are zero
>
> 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](https://docs.flowx.ai/6.x/observatory/sdk/event-reporting.md) for the rules.

***

## Related resources

> [card] [SDK decorators](https://docs.flowx.ai/6.x/observatory/sdk/decorators.md)
>
> Full reference for `@agent`, `@chain`, and `@tool`.

> [card] [Observability overview](https://docs.flowx.ai/6.x/observatory/observability/overview.md)
>
> What you can do once traces are flowing.


## Related topics

- [Agent Builder](https://docs.flowx.ai/6.x/ai-platform/agent-builder/overview.md)
- [Navigation areas](https://docs.flowx.ai/6.x/docs/building-blocks/process/navigation-areas.md)
- [Observatory](https://docs.flowx.ai/6.x/observatory/overview.md)
- [Self-hosted setup](https://docs.flowx.ai/6.x/observatory/setup/self-hosted.md)
- [Glossary](https://docs.flowx.ai/6.x/docs/getting-started/glossary.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.