SDK Documentation

pip install agentcost

cd agentcost-sdk
pip install -e .

from agentcost import track_costs

# Initialize tracking
track_costs.init(
    api_key="sk_...",  # Settings → your project → API Key
    project_id="123e4567-e89b-42d3-a456-426614174000"  # Settings → your project → UUID
)

# OpenAI — automatically tracked
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Hello!"}])

# Anthropic — automatically tracked
from anthropic import Anthropic
client = Anthropic()
message = client.messages.create(model="claude-3-5-sonnet-20241022", max_tokens=100, messages=[{"role": "user", "content": "Hello!"}])

# Gemini — automatically tracked (Google Gen AI SDK)
from google import genai
client = genai.Client()
response = client.models.generate_content(model="gemini-2.5-flash", contents="Hello!")

# LangChain — automatically tracked
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4")
response = llm.invoke("Hello, world!")  # Automatically tracked

# Push any batched events to the backend immediately
track_costs.flush()

# Now open your dashboard — the calls above should be there.

track_costs.init(
    # Required for cloud mode
    api_key="sk_...",
    project_id="123e4567-e89b-42d3-a456-426614174000",  # project UUID, not its name

    # Optional settings
    base_url="https://api.agentcost.tech",  # Your backend URL
    batch_size=10,                          # Events before auto-flush
    flush_interval=5.0,                     # Seconds between flushes
    debug=True,                             # Enable debug logging
    default_agent_name="my-agent",          # Default agent tag
    local_mode=False,                       # Store locally (no backend)
    enabled=True,                           # Enable/disable tracking

    # Custom pricing (overrides defaults)
    custom_pricing={
        "my-custom-model": {"input": 0.001, "output": 0.002}
    },

    # Global metadata (attached to all events)
    global_metadata={
        "environment": "production",
        "version": "1.0.0"
    }
)

# Option 1: Set default agent
track_costs.set_agent_name("router-agent")

# Option 2: Context manager (recommended)
with track_costs.agent("technical-agent"):
    llm.invoke("How do I fix this bug?")  # Tagged as "technical-agent"

with track_costs.agent("billing-agent"):
    llm.invoke("What's my balance?")  # Tagged as "billing-agent"

with track_costs.workflow("support-triage"):

    with track_costs.step("classify"):
        llm.invoke("Which queue does this belong in?")

    with track_costs.tool("search_docs"):
        llm.invoke("Summarise these results")

    with track_costs.step("draft_reply"):
        llm.invoke("Write the response")

with track_costs.workflow("support-triage"):
    ticket = handle(request)
    track_costs.outcome(ticket.resolved, label=ticket.status)

export AGENTCOST_TRACE_ID=0532f9c4-a022-4e98-a543-d8e17c5b90a6
export AGENTCOST_WORKFLOW=refactor-run   # optional, names the run

# What do the prompt and skill files cost on every call?
agentcost analyze ./agent --model gpt-4o

# Record a test run with local mode, then project it to production
agentcost analyze ./agent --events run.json --runs-per-day 2000

import json
from agentcost import track_costs

track_costs.init(local_mode=True)

with track_costs.workflow("support-triage"):
    ...   # run your agent once

track_costs.flush()
json.dump(track_costs.get_local_events(), open("run.json", "w"))

# Persistent metadata (attached to all subsequent events)
track_costs.add_metadata("user_id", "user_123")
track_costs.add_metadata("tenant_id", "acme_corp")

# Temporary metadata (context manager)
with track_costs.metadata(conversation_id="conv_456", step="routing"):
    llm.invoke("Route this query")

track_costs.init(local_mode=True, debug=True)

# Make LLM calls
llm.invoke("Hello!")
llm.invoke("World!")

# Retrieve captured events
events = track_costs.get_local_events()
for event in events:
    print(f"Model: {event['model']}")
    print(f"Tokens: {event['total_tokens']}")
    print(f"Cost: ${event['cost']:.6f}")

# Sync streaming
for chunk in llm.stream("Tell me a story"):
    print(chunk.content, end="")
# Event recorded after stream completes

# Async streaming
async for chunk in llm.astream("Tell me a story"):
    print(chunk.content, end="")
# Event recorded after stream completes

{
  "agent_name": "my-agent",
  "model": "gpt-4o",
  "input_tokens": 1500,
  "output_tokens": 80,
  "total_tokens": 1580,
  "cached_tokens": 1200,
  "cost": 0.0031,
  "latency_ms": 1234,
  "timestamp": "2026-08-15T10:30:45.123Z",
  "success": true,
  "error": null,
  "streaming": false,
  "metadata": {"conversation_id": "conv_456"}
}

# Send pending events
track_costs.flush()

# Full shutdown
track_costs.shutdown()

# The SDK never throws exceptions to your code
try:
    response = llm.invoke("Hello!")  # This works even if tracking fails
except Exception as e:
    # This will only catch LLM errors, not tracking errors
    print(f"LLM error: {e}")

# To see tracking errors, enable debug mode
track_costs.init(
    api_key="sk_...",
    project_id="123e4567-e89b-42d3-a456-426614174000",
    debug=True,  # Logs errors to console
)