---
title: "Quickstart"
description: "Zero to your first agent trace in 5 minutes."
---

## What you'll build

By the end of this page you'll have LangSight running locally and capturing
every tool call your AI agent makes — with full traces visible in both the
CLI and the dashboard.

## Prerequisites

- Python 3.11+
- Docker Desktop (recommended) — or skip Docker for CLI-only use

---

## 1. Choose your path

<Tabs>
  <Tab title="Full dashboard (recommended)">
    See LangSight with realistic demo data — 30 agent sessions, health history,
    security findings, and cost attribution, all pre-loaded:

    ```bash
    git clone https://github.com/LangSight/langsight && cd langsight
    ./scripts/quickstart.sh      # generates secrets, writes .env, starts everything
    ```

    Open **http://localhost:3003** and log in. The dashboard is fully populated
    with a demo project — explore Sessions, Health, Security, Costs, and Agents
    pages to see what LangSight captures.

    <Note>
      The demo data includes multi-agent sessions with handoffs, MCP server
      health history (mix of UP/DEGRADED/DOWN), security scan findings, and
      per-agent cost breakdowns. Everything you see is what your real agent
      data will look like.
    </Note>
  </Tab>
  <Tab title="CLI only (no Docker)">
    The CLI works immediately with zero config — no server, no database:

    ```bash
    pip install langsight           # or: uv tool install langsight
    langsight init                  # discovers MCP servers from Claude/Cursor/VS Code
    langsight mcp-health            # instant health check results
    langsight security-scan         # OWASP + CVE scan findings
    ```

    Results are displayed in the terminal. When you're ready for the full
    dashboard experience, come back and run `./scripts/quickstart.sh`.
  </Tab>
</Tabs>

## 2. Instrument your agent

Add 3 lines to your existing agent code. LangSight wraps your MCP client
and captures every `call_tool()` automatically — fire-and-forget, fail-open.

```python
from langsight.sdk import LangSightClient

# Connect to your LangSight server
langsight = LangSightClient(url="http://localhost:8000")

# Wrap your MCP session — every call_tool() is now traced
traced = langsight.wrap(
    mcp_session,                     # your existing MCP client
    server_name="postgres-mcp",      # which server this is
    agent_name="my-agent",           # which agent is calling
    session_id="sess-001",           # groups calls into one session
)

# Use traced exactly like your original session — the API is identical
result = await traced.call_tool("query", {"sql": "SELECT 1"})
#        ↑ this call is traced automatically
```

<Note>
  `wrap()` returns a transparent proxy. It intercepts `call_tool()` and
  `list_tools()`, records timing and status, and sends spans asynchronously.
  If LangSight is unreachable, your agent works normally — nothing breaks.
</Note>

### Using a framework? Even simpler.

<Tabs>
  <Tab title="LangChain / LangGraph">
    ```python
    from langsight.integrations.langchain import LangSightLangChainCallback

    langsight = LangSightClient(url="http://localhost:8000")
    callback = LangSightLangChainCallback(client=langsight, agent_name="my-agent")

    # Pass as a callback — all tool calls traced automatically
    agent.invoke({"input": "..."}, config={"callbacks": [callback]})
    ```
  </Tab>
  <Tab title="CrewAI">
    ```python
    from langsight.integrations.crewai import LangSightCrewAICallback

    langsight = LangSightClient(url="http://localhost:8000")
    callback = LangSightCrewAICallback(client=langsight)

    crew = Crew(agents=[...], tasks=[...], callbacks=[callback])
    crew.kickoff()
    ```
  </Tab>
  <Tab title="Pydantic AI">
    ```python
    from langsight.integrations.pydantic_ai import langsight_tool

    langsight = LangSightClient(url="http://localhost:8000")

    @langsight_tool(client=langsight, server_name="postgres-mcp")
    async def query_db(sql: str) -> list[dict]:
        return await session.call_tool("query", {"sql": sql})
    ```
  </Tab>
</Tabs>

## 3. See your first trace

Run your agent, then check results:

<Tabs>
  <Tab title="CLI">
    ```bash
    langsight sessions
    ```

    ```
    Agent Sessions                             last 24 hours
    ──────────────────────────────────────────────────────────────
    Session       Agent         Duration   Tools   Errors   Cost
    sess-001      my-agent      1,482ms       5        0   $0.02
    ```

    Drill into a session:

    ```bash
    langsight sessions --id sess-001
    ```

    ```
    Session: sess-001  |  1 agent  |  5 tool calls  |  0 failures

    ├── [MCP] postgres-mcp/query          42ms  ✓
    ├── [MCP] postgres-mcp/list_tables    18ms  ✓
    ├── [MCP] postgres-mcp/query          89ms  ✓
    ├── [MCP] slack-mcp/send_message     210ms  ✓
    └── [MCP] slack-mcp/send_message     180ms  ✓
    ```
  </Tab>
  <Tab title="Dashboard">
    Open **http://localhost:3003** and navigate to **Sessions**.

    You'll see a full call tree with timing, status, payloads, and cost
    attribution for every tool call your agent made.
  </Tab>
</Tabs>

## 3 (optional). Add prevention guardrails

Prevent runaway loops and budget overruns with a few extra parameters:

```python
client = LangSightClient(
    url="http://localhost:8000",
    loop_detection=True,   # stop if agent loops the same call 3x
    max_steps=25,          # hard stop at 25 tool calls per session
    circuit_breaker=True,  # auto-disable servers after 5 consecutive failures
)
```

See [Prevention Guardrails](/sdk/python#prevention-guardrails) for full configuration options.

## 4. What's next

You now have full traces of every tool call. Here's what LangSight does beyond tracing:

<CardGroup cols={2}>
  <Card title="MCP Health Monitoring" icon="heart-pulse" href="/cli/mcp-health">
    Continuous uptime and latency checks for every MCP server.
    Detects schema drift and fires alerts on state changes.
  </Card>
  <Card title="Security Scanning" icon="shield-halved" href="/cli/security-scan">
    OWASP MCP Top 10 checks, CVE scanning, tool poisoning
    detection, and auth auditing — built in.
  </Card>
  <Card title="Cost Attribution" icon="coins" href="/costs-model-pricing">
    Per-agent, per-tool, per-session cost breakdown with
    model pricing database (Claude, GPT, Gemini, Llama).
  </Card>
  <Card title="SLOs & Alerting" icon="bell" href="/slos">
    Define success rate and latency SLOs per agent.
    Get Slack alerts on breaches and anomalies.
  </Card>
</CardGroup>

### Multi-agent tracing

If your agent hands off to sub-agents, LangSight captures the full tree:

```python
from langsight.sdk import LangSightClient
from langsight.sdk.models import ToolCallSpan

langsight = LangSightClient(url="http://localhost:8000")
trace_id = "trace-abc"
session_id = "sess-002"

# Orchestrator wraps its MCP client
orchestrator = langsight.wrap(
    mcp, server_name="jira-mcp",
    agent_name="orchestrator", trace_id=trace_id, session_id=session_id,
)

# When handing off, create a handoff span
handoff = ToolCallSpan.handoff_span(
    from_agent="orchestrator", to_agent="research-agent",
    trace_id=trace_id, session_id=session_id,
)
await langsight.send_span(handoff)

# Sub-agent wraps with parent_span_id → links to the handoff
researcher = langsight.wrap(
    mcp, server_name="confluence-mcp",
    agent_name="research-agent", trace_id=trace_id, session_id=session_id,
    parent_span_id=handoff.span_id,
)
```

The dashboard renders this as a single connected tree across all agents.

<CardGroup cols={2}>
  <Card title="Python SDK Reference" icon="code" href="/sdk/python">
    Full API reference with all options.
  </Card>
  <Card title="Self-Hosting Guide" icon="server" href="/self-hosting/docker-compose">
    Production deployment with Postgres + ClickHouse.
  </Card>
</CardGroup>
