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

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](./setup/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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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={"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>
      Treat the API key like a database password. Don't commit it to source control.
    </Warning>
  </Step>

  <Step title="Install the SDK">
    Add the SDK to your Python project:

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

  <Step title="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={"system"}
    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.
    </Tip>
  </Step>

  <Step title="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.

    <Check>
      You see a row for your run with status `success`, the right agent name, and a non-zero duration.
    </Check>
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## Validate the rest of the platform

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

<CardGroup cols={2}>
  <Card title="Analytics" icon="chart-line" href="./observability/analytics">
    p50/p95 latency, cost by model, error rate.
  </Card>

  <Card title="Risk Dashboard" icon="triangle-exclamation" href="./governance/risk-dashboard">
    The 6-dimensional risk score updates automatically.
  </Card>

  <Card title="Compliance heatmap" icon="grid" href="./compliance/gap-analysis-heatmap">
    Controls start evaluating against the new evidence.
  </Card>

  <Card title="ROI overview" icon="dollar-sign" href="./roi/overview">
    Configure baselines to start producing ROI numbers.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="No traces appear after 30 seconds" icon="circle-question">
    * 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>

  <Accordion title="Traces show but the agent name is empty" icon="circle-question">
    The function must be decorated with `@agent("name")` (not bare `@agent`). The string is what populates the **Agent** column.
  </Accordion>

  <Accordion title="Token counts are zero" icon="circle-question">
    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](./sdk/event-reporting) for the rules.
  </Accordion>
</AccordionGroup>

***

## Related resources

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

  <Card title="Observability overview" icon="eye" href="./observability/overview">
    What you can do once traces are flowing.
  </Card>
</CardGroup>