Python SDK

Python 3.10+. A run context manager (sync + async), one-line auto-instrumentation for Anthropic and OpenAI, and non-blocking background delivery.

Install

pip install "agentping-sdk @ git+https://github.com/agent-ping/agent-ping-python.git"

The import name is agentping. Single runtime dependency: httpx.

Quickstart

import agentping

agentping.init()  # reads AGENTPING_API_KEY from the environment

with agentping.run("support-triage", customer_id="acme-corp",
                   goal="Triage the ticket and route it correctly") as r:
    r.event("log", {"message": "classifying ticket"})
    r.event("llm_call", {
        "provider": "anthropic",
        "model": "claude-sonnet-4-5",
        "input_tokens": 1024,
        "output_tokens": 312,
        "latency_ms": 1430,
    })
    r.score("confidence", 0.93)

The context manager finishes with status="success" on clean exit and status="failed" (capturing repr(exc) into output.error) on exception. r.id is populated before the with block enters. The optional goal tells evaluations what the run was supposed to achieve.

Auto-instrumentation

Each provider has its own one-line patch. Call once at module load; the patch is idempotent and global. LLM calls inside an active agentping.run(...) emit llm_call events with provider, model, token counts, and latency. Cost is computed server-side.

import agentping

agentping.init()

# Each line is independent; enable only what you use:
agentping.instrument_anthropic()    # Claude: Messages API, streaming, tool use
agentping.instrument_openai()       # GPT: chat.completions, responses, streaming

For any other provider or framework, report the call yourself with r.event("llm_call", {...}); cost is computed server-side from the same rate card.

If the installed provider SDK is outside the supported range, the patch is skipped and a single warning is logged. AgentPing's SDK never blocks user code; if a wrapper hits an internal error the request still completes normally and only the telemetry is lost.

Heartbeats

agentping.heartbeat(
    "daily-summary",
    status="ok",
    cost_usd=0.084,
    duration_ms=12_300,
    metadata={"items": 47},
)

Same table as full runs. Upgrading later requires no data migration.

Context propagation

# Env var, picked up automatically on init:
# AGENTPING_PARENT_RUN=run_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6

# Explicit parameter:
with agentping.run("price-fetcher",
                   parent_run_id="run_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6"):
    ...

Explicit parameter wins over env var.

Flushing

Telemetry flushes automatically on exit (atexit). In a long-running worker that never exits, call agentping.flush() at the end of each unit of work. agentping.status() returns queue depth and the last error for debugging.

Configuration

init() accepts the same values plus queue_size (default 1000) and a custom transport for testing.

Use the team API key (apk_<region>_<32 hex>) for the SDK. Ping tokens (ping_...) are for URLs only.

Source

github.com/agent-ping/agent-ping-python. Public surface in src/agentping/__init__.py.