Skip to main content
Use this guide to connect a TypeScript or Python agent runtime to Pylva.

​
1. Install the SDK

pnpm add @pylva/sdk
pip install pylva-sdk
The Python package installs from pylva-sdk, but the runtime import is pylva.

​
2. Create an Agent SDK key

Sign in to the Pylva dashboard and create an Agent SDK key. Store the plaintext key as PYLVA_API_KEY in your runtime secret store. The key is shown once.

​
3. Initialize the SDK

​
TypeScript

import { init } from "@pylva/sdk";

init({
  apiKey: process.env.PYLVA_API_KEY!,
});

​
Python

import os
import pylva

pylva.init(api_key=os.environ["PYLVA_API_KEY"])
The default cloud endpoint is https://api.pylva.com. Self-hosted deployments can pass an endpoint override.

​
4. Attribute calls to a customer and step

​
TypeScript

import { track } from "@pylva/sdk";

await track(
  "acme-corp",
  { step: "evaluate" },
  async () => {
    return openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages,
    });
  },
);

​
Python

from pylva import track_context

with track_context(customer_id="acme-corp", step="evaluate"):
    response = openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,
    )

​
5. Check the dashboard

After events arrive, use the dashboard to review:
  • Total cost and cost by customer.
  • Expensive agent steps.
  • Unknown pricing tasks that need a pricing rule.
  • Rule events, warnings, and alerts.

​
Production checklist

  • Use opaque customer_id values.
  • Use stable step labels such as retrieve_context, evaluate, or summarize.
  • Do not send prompts, completions, emails, phone numbers, or raw messages in telemetry metadata.
  • Configure pricing for any non-LLM metrics before relying on margin reports.