---
title: Python SDK
description: Install, auto-instrument, and inspect AgentPing from Python 3.10 and up.
section: sdks
order: 1
---

# 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

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

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

## Quickstart

```python
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.

```python
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

```python
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

```python
# 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](https://github.com/agent-ping/agent-ping-python). Public surface in `src/agentping/__init__.py`.