Agent Cost & UsagePython SDK Quickstart

Python SDK Quickstart

Use this guide to connect a Python agent to Mavvrik, capture model usage and cost, and verify the resulting execution trace.

Requirements

You need:

a Python agent application;
a supported AI provider or framework;
permission to register an agent in Mavvrik.

See Supported Agentic Stacks for compatibility.

1. Register the agent

Complete Register an Agent, then copy:

tenant ID;
agent ID;
API key.

Keep the Agent ID stable. Mavvrik uses it to attribute captured activity and cost to the agent.

2. Install the SDK

For most Python agents, install the GenAI bundle:

Bash

pip install "mvk-sdk-py[genai]~=1.3.0"

~=1.3.0 keeps the application on the compatible 1.3.x series documented here.

To install only specific integrations:

Bash

# OpenAI only
pip install "mvk-sdk-py[openai]~=1.3.0"

# Multiple integrations
pip install "mvk-sdk-py[openai,anthropic,langchain]~=1.3.0"

Available bundles:

Bundle	Includes
`[genai]`	Supported AI providers
`[frameworks]`	Supported agent frameworks
`[vectordb]`	Supported vector databases
`[all]`	All Python integrations

3. Configure the SDK

Bash

export MVK_TENANT_ID="your-tenant-id"
export MVK_AGENT_ID="your-agent-id"
export MVK_API_KEY="your-api-key"

Optional global settings:

Bash

export MVK_TAG_ENV="production"
export MVK_TAG_REGION="us-east-1"
export MVK_LOG_LEVEL="INFO"

Store the API key in the deployment environment or secret manager. Do not commit it to source control.

4. Initialize Mavvrik before supported AI libraries

Call mvk.instrument() before importing or creating clients from libraries that Mavvrik should instrument.

Python

import mvk_sdk as mvk

mvk.instrument(
    wrappers={"include": ["genai"]}
)

from openai import OpenAI

The quickstart intentionally enables only genai. Add vectordb when retrieval activity should also be captured.

Credentials can also be passed directly for local testing:

Python

import mvk_sdk as mvk

mvk.instrument(
    tenant_id="your-tenant-id",
    agent_id="your-agent-id",
    api_key="your-api-key",
    wrappers={"include": ["genai"]},
)

Environment variables take precedence over values passed to mvk.instrument().

5. Make a supported AI call

Existing provider calls do not need to be replaced with Mavvrik-specific APIs.

Python

import mvk_sdk as mvk

mvk.instrument(wrappers={"include": ["genai"]})

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Summarize this claim in one sentence."}
    ],
)

print(response.choices[0].message.content)

What Mavvrik captures automatically

For supported calls, Mavvrik records the telemetry exposed by the provider or library, including:

provider and model;
input/output token or equivalent usage quantities;
cached and reasoning token fields where available;
request duration;
success/failure and error information;
trace relationships;
pricing inputs used by Mavvrik to calculate cost.

6. Verify the integration

Run one known test request, then open:

Home → Agentic → Cost — confirm the agent shows new spend.
Home → Agentic → Sessions — inspect the captured operation and trace.

Allow up to 10 minutes for processed activity to appear.

Inspect telemetry locally

Bash

export MVK_EXPORTER_TYPE=console
export MVK_EXPORTER_FORMAT=json

To confirm which integrations attached successfully:

Bash

export MVK_LOG_LEVEL=DEBUG

If an expected library is missing, confirm that Mavvrik initialized before that library was imported and that the installed library version is recognized by the installed SDK.

Provider and framework examples

OpenAI

Python

import mvk_sdk as mvk

mvk.instrument(wrappers={"include": ["genai"]})

from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain this invoice."}],
)

Anthropic

Python

import mvk_sdk as mvk

mvk.instrument(wrappers={"include": ["genai"]})

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarize this claim."}],
)

Amazon Bedrock

Python

import mvk_sdk as mvk

mvk.instrument(wrappers={"include": ["genai"]})

import boto3
import json

client = boto3.client("bedrock-runtime")
response = client.invoke_model(
    modelId="anthropic.claude-sonnet-4-5-v1:0",
    body=json.dumps({
        "messages": [{"role": "user", "content": "Summarize this claim."}]
    }),
)

LangChain / LangGraph

Bash

pip install "mvk-sdk-py[openai,langchain]~=1.3.0"

Python

import mvk_sdk as mvk

mvk.instrument(
    wrappers={"include": ["genai", "langchain"]}
)

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini")
result = llm.invoke("Summarize this claim.")

Framework activity and supported model calls appear in the same execution trace.

RAG agent

Python

mvk.instrument(
    wrappers={"include": ["genai", "vectordb"]}
)

OpenRouter

Python

import mvk_sdk as mvk

mvk.instrument(wrappers={"include": ["genai"]})

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-***",
)

response = client.chat.completions.create(
    model="anthropic/claude-3.5-sonnet",
    messages=[{"role": "user", "content": "Summarize this in one line."}],
)

Routing-aware model/provider fields are recorded when the source exposes them.

Add business context

Use mvk.context() to attribute captured cost and usage to a customer, user, session, application, use case, request, region, or tags.

Python

with mvk.context(
    customer_id="acme",
    user_id="user-123",
    session_id="session-456",
    use_case="customer_support",
):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Summarize this case."}],
    )

See Add Business Context.

Track metered non-LLM usage

Use metered usage when the workflow consumes a paid resource that Mavvrik cannot price automatically.

Python

mvk.add_metered_usage([
    {
        "metric_kind": "eligibility_api.request",
        "quantity": 1,
        "uom": "call",
        "metadata": {
            "rate_per_unit": 0.05,
            "currency": "USD",
            "provider": "eligibility-service",
        },
    }
])

Add a signal when the operation should also appear as a named trace step.

See Track Metered Usage.

Start without application code changes

Bash

export MVK_TENANT_ID="your-tenant-id"
export MVK_AGENT_ID="your-agent-id"
export MVK_API_KEY="your-api-key"

mvk-instrument python your_app.py

To prepare a host or image for automatic startup:

Bash

mvk-sdk install --auto-instrument

Instrument web applications

Python

import mvk_sdk as mvk
from fastapi import FastAPI
from mvk_sdk.middleware import MVKASGIMiddleware

mvk.instrument(wrappers={"include": ["genai"]})

app = FastAPI()
app.add_middleware(
    MVKASGIMiddleware,
    exclude_paths=["/health", "/ready", "/metrics"],
    propagate_response_headers=True,
)

Instrument serverless and short-lived jobs

For AWS Lambda:

Python

import mvk_sdk as mvk
from mvk_sdk import lambda_handler

mvk.instrument(wrappers={"include": ["genai"]})

@lambda_handler()
def handler(event, context):
    return do_work(event)

For an unsupported short-lived environment, flush before returning:

Python

from mvk_sdk import force_flush

def handler(event, context):
    try:
        return do_work(event)
    finally:
        force_flush()

Short-lived scripts can call:

Python

mvk.shutdown()

before process exit.

Verify the complete setup

Agent registered in Mavvrik.
MVK_TENANT_ID, MVK_AGENT_ID, and MVK_API_KEY configured.
SDK pinned to the documented 1.3.x series.
mvk.instrument() runs before supported provider/framework imports.
One known AI request completed.
Agent activity appears in Home → Agentic → Cost.
Execution detail appears in Home → Agentic → Sessions.
Required business context is attached.
Metered non-LLM usage is recorded where it contributes to total cost.

If any item fails, use Troubleshooting Agent Data.