Python SDK

Python 3.10+. A run context manager (sync + async), one-line auto-instrumentation for six LLM providers and four frameworks, and non-blocking background delivery.

Install

pip install agentping-sdk

The distribution is named agentping-sdk on PyPI; 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") 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.

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()

# LLM providers (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
agentping.instrument_gemini()       # Gemini: generate_content, streaming, embed_content
agentping.instrument_mistral()      # Mistral: chat.complete, stream
agentping.instrument_cohere()       # Cohere: chat, chat_stream, embed

# Frameworks (each line is independent):
agentping.instrument_pydantic_ai()  # Patches Agent.run / run_sync
agentping.instrument_crewai()       # Patches Crew.kickoff
agentping.instrument_openai_agents()  # Auto-attaches AgentPingHooks to Runner.run

# Framework handler classes (attach manually, idiomatic for the framework):
# agentping.AgentPingCallbackHandler : LangChain (see /docs/frameworks/langchain)
# agentping.AgentPingHooks           : OpenAI Agents (see /docs/frameworks/openai-agents)

Install only the extras you need:

pip install "agentping-sdk[anthropic,openai]"          # just the marquee two
pip install "agentping-sdk[gemini,mistral,cohere]"     # more providers
pip install "agentping-sdk[langchain,pydantic-ai,crewai,openai-agents]"  # frameworks

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

Variable	Default
`AGENTPING_API_KEY`	required
`AGENTPING_BASE_URL`	auto-derived from key region (`https://<region>.ingest.agentping.io`)
`AGENTPING_PARENT_RUN`	optional

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.