AgentPing Python SDK
Official Python SDK for AgentPing — phone call alerts when your AI agent needs you.
Install
pip install agentping-sdk
Quick start
from agentping import AgentPingClient
client = AgentPingClient(api_key="ap_sk_...")
# Send an alert (voice call with retry)
alert = client.send_alert(
title="Deploy approval needed",
severity="normal",
message="v2.4.1 ready for production. 3 migrations pending.",
alert_type="approval",
)
print(alert["id"]) # "550e8400-..."
print(alert["status"]) # "waiting_for_primary_ack"
# Check status later
status = client.get_alert(alert["id"])
print(status["status"]) # "acknowledged", "escalating", etc.
# Acknowledge programmatically (stops escalation)
ack = client.acknowledge(alert["id"])
print(ack["status"]) # "acknowledged"
Agent framework integration
The SDK includes an OpenAI-compatible tool definition you can plug into any agent framework:
from agentping import AgentPingClient, tool_definition, handle_tool_call
client = AgentPingClient(api_key="ap_sk_...")
# 1. Add to your agent's tools
tools = [tool_definition()]
# 2. When the agent calls the tool, handle it:
# (assuming `tool_call` is the parsed tool call from your framework)
import json
args = json.loads(tool_call.function.arguments)
result = handle_tool_call(client, args)
OpenAI example
from openai import OpenAI
from agentping import AgentPingClient, tool_definition, handle_tool_call
import json
openai = OpenAI()
agentping = AgentPingClient(api_key="ap_sk_...")
messages = [
{"role": "system", "content": """You are a helpful assistant.
When you need the user's attention and they haven't responded to your message,
use the agentping_alert tool to escalate via voice call.
Always try messaging in chat first — use agentping_alert as a fallback."""},
{"role": "user", "content": "Monitor my deploy and alert me if it fails."},
]
response = openai.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=[tool_definition()],
)
# Handle tool calls
for tool_call in response.choices[0].message.tool_calls or []:
if tool_call.function.name == "agentping_alert":
args = json.loads(tool_call.function.arguments)
result = handle_tool_call(agentping, args)
print(f"Alert sent: {result['id']}")
Anthropic Claude example
from anthropic import Anthropic
from agentping import AgentPingClient, tool_definition, handle_tool_call
import json
anthropic = Anthropic()
agentping = AgentPingClient(api_key="ap_sk_...")
# Convert OpenAI tool format to Anthropic format
openai_tool = tool_definition()
anthropic_tool = {
"name": openai_tool["function"]["name"],
"description": openai_tool["function"]["description"],
"input_schema": openai_tool["function"]["parameters"],
}
response = anthropic.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="""You are a helpful assistant.
When you need the user's attention and they haven't responded,
use the agentping_alert tool to escalate via voice call.""",
messages=[{"role": "user", "content": "Monitor my deploy and alert me if it fails."}],
tools=[anthropic_tool],
)
# Handle tool use
for block in response.content:
if block.type == "tool_use" and block.name == "agentping_alert":
result = handle_tool_call(agentping, block.input)
print(f"Alert sent: {result['id']}")
Severity levels
| Severity | Behavior |
|---|---|
normal |
Voice call with retries (2 min apart), respects quiet hours |
critical |
Voice call with retries, bypasses quiet hours |
Deprecated:
low,urgent, andpersistent_criticalare still accepted for backwards compatibility.persistent_criticalmaps tocritical; others map tonormal.
Alert types
| Type | Default Delay | Use when |
|---|---|---|
approval |
300s (5 min) | Agent needs a decision |
task_failure |
120s (2 min) | Something broke |
threshold |
600s (10 min) | Metric crossed a boundary |
reminder |
300s (5 min) | Time-sensitive nudge |
other |
0s (immediate) | General escalation |
Error handling
from agentping import AgentPingClient, RateLimitError, ForbiddenError
client = AgentPingClient(api_key="ap_sk_...")
try:
client.send_alert(title="Test", severity="normal")
except RateLimitError:
print("Too many alerts — wait before retrying")
except ForbiddenError as e:
print(f"Policy violation: {e}")
API reference
AgentPingClient(api_key, base_url=..., timeout=30.0)— create a clientclient.send_alert(title, severity, message=..., alert_type=..., delay_seconds=..., phone_number=..., expires_in_minutes=..., metadata=...)— create an alertclient.get_alert(alert_id)— get alert statusclient.acknowledge(alert_id, ack_source="api")— acknowledge an alertclient.close()— close the HTTP client (also works as a context manager)
Links
Metadata
Release files for agentping-sdk 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentping_sdk-0.1.2.tar.gz | 16.7 kB | Without provenance | Details for agentping_sdk-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentping_sdk-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for agentping_sdk-0.1.2-py3-none-any.whl |
Total release size: 24.0 kB
Release files / agentping_sdk-0.1.2.tar.gz
| Download URL | agentping_sdk-0.1.2.tar.gz |
|---|---|
| Size | 16.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
993b4b11e4e2c2cd829bee759ae2f62a3f4205e89bfc70bba5ff143618fc4c36
|
|
BLAKE2b-256 checksum How to use checksums |
962709306cbc96e98bcb1f3bc039ae4438154657216d619e32f142dc05a9cfc7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Release files / agentping_sdk-0.1.2-py3-none-any.whl
| Download URL | agentping_sdk-0.1.2-py3-none-any.whl |
|---|---|
| Size | 7.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4da3a801557e3ed8956a33d88fd575f6e0ea5ec5d804ccaa7a799f1f79ec7b13
|
|
BLAKE2b-256 checksum How to use checksums |
58b94443ac55563d33174282d207ec0cea1b720df9f3a4f1b2c0dc5504848f1c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.10
|
Security for agentping-sdk 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.