Lago Agent SDK

Documentation Index

Fetch the complete documentation index at: https://getlago.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

• Python: lago-agent-sdk on PyPI.
• JavaScript / TypeScript: @getlago/agent-sdk on npm.

​

How it works

                  ┌────────────────┐
your code ──────▶ │ wrapped client │ ──────▶ provider (Bedrock / Mistral / …)
                  └────────┬───────┘
                           │ (extract usage)
                           ▼
                  ┌────────────────┐
                  │  Lago events   │ ──────▶ api.getlago.com
                  └────────────────┘

• Wraps your existing LLM client in place. Your application code does not change.
• Extracts usage from each response into a normalized shape (CanonicalUsage).
• Buffers events in memory and flushes them in batches to Lago’s /events/batch endpoint.
• Survives provider and Lago outages with exponential backoff and a bounded buffer.
• p99 wrap overhead under 5 ms. Your LLM call is never blocked on Lago.
• Never breaks your LLM call. Instrumentation errors are caught, logged, and optionally forwarded to your observability stack.

​

Supported providers

​

Quickstart

pip install lago-agent-sdk

# Optional extras for your provider:
pip install 'lago-agent-sdk[bedrock]'   # adds boto3
pip install 'lago-agent-sdk[mistral]'   # adds mistralai

import boto3
from lago_agent_sdk import LagoSDK

sdk = LagoSDK(
    api_key="<YOUR_LAGO_API_KEY>",
    default_subscription_id="sub_acme",
)
client = sdk.wrap(boto3.client("bedrock-runtime", region_name="eu-west-1"))

resp = client.converse(
    modelId="eu.amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Hello"}]}],
)

sdk.flush()

​

Mistral quickstart

from mistralai.client import Mistral
from lago_agent_sdk import LagoSDK

sdk = LagoSDK(api_key="...", default_subscription_id="sub_acme")
client = sdk.wrap(Mistral(api_key="..."))

resp = client.chat.complete(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Hello"}],
)
sdk.flush()

​

Captured token dimensions

​

Provider coverage

​

Multi-tenant: pick a subscription per call

1. Per-call override: highest precedence, attached to the individual request.
2. Context-bound: set once per request handler. Propagates safely across async boundaries.
3. Default at init: fallback if nothing else is set.

# 1. Per-call override (highest precedence)
client.converse(
    modelId="eu.amazon.nova-lite-v1:0",
    messages=[{"role": "user", "content": [{"text": "Hello"}]}],
    extra_lago={
        "subscription": "sub_acme",
        "dimensions": {"feature": "summarize", "user_id": "u_42"},
    },
)

# 2. Context-bound. Propagates across asyncio tasks via contextvars.
sdk.set_subscription("sub_acme")
# all calls in this thread/asyncio task → sub_acme

# 3. Default at init (fallback)
sdk = LagoSDK(api_key="...", default_subscription_id="sub_default")

​

Configuration reference

​

Custom metric codes

from lago_agent_sdk import LagoConfig, LagoSDK

sdk = LagoSDK(
    api_key="...",
    config=LagoConfig(
        api_key="...",
        metric_codes={
            "input": "ai_input_tokens",
            "output": "ai_output_tokens",
        },
    ),
)

​

Error handling

import sentry_sdk
from lago_agent_sdk import LagoConfig, LagoSDK

def on_error(exc: Exception, where: str) -> None:
    sentry_sdk.capture_exception(exc, tags={"sdk_phase": where})

sdk = LagoSDK(
    api_key="...",
    config=LagoConfig(api_key="...", on_error=on_error),
)

​

Exception hierarchy

• LagoSDKError: base class for every SDK-raised error.
• LagoApiError: non-2xx response from Lago.
• LagoConfigError: invalid configuration at init time.
• UnknownClientError: wrap() was called on a client the SDK does not recognize.

​

Verify the integration

​

Resources

• Python SDK: GitHub · PyPI · CHANGELOG
• JavaScript SDK: GitHub · npm · CHANGELOG
• Per-token pricing example: Template
• Billable metric API: Create a billable metric
• Charges with filters: Guide