agentphone 0.2.0

AgentPhone Python SDK — give your AI agents phone numbers, SMS, and voice calls

AgentPhone Python SDK

Official Python SDK for AgentPhone — give your AI agents real phone numbers, SMS, and voice calls.

Installation

pip install agentphone

For async support:

pip install agentphone[async]

Quickstart

from agentphone import AgentPhone

client = AgentPhone(api_key="your-api-key")

# Create an agent and buy a number
agent = client.agents.create(name="My Agent")
number = client.numbers.buy(country="US", agent_id=agent.id)

# Make an AI conversation call — no webhook needed
call = client.calls.make_conversation(
    agent_id=agent.id,
    to_number="[phone]",
    topic="You are a friendly assistant. Ask about their day.",
    initial_greeting="Hey! This is an AI calling from AgentPhone.",
)
print(call.status)  # registered

Async

from agentphone import AsyncAgentPhone

async with AsyncAgentPhone(api_key="your-api-key") as client:
    numbers = await client.numbers.list()
    call = await client.calls.make_conversation(...)

Resources

Resource	Methods
client.numbers	list(), buy(), release(), get_messages()
client.agents	list(), create(), get(), attach_number()
client.calls	list(), get(), make(), make_conversation()
client.conversations	list(), get()
client.webhooks	get(), set(), delete(), list_deliveries(), test()

Webhook Verification

from agentphone import construct_event, WebhookVerificationError

@app.post("/webhook")
async def handle(request: Request):
    body = await request.body()
    sig = request.headers["X-Webhook-Signature"]
    try:
        event = construct_event(body, sig, secret="whsec_...")
    except WebhookVerificationError:
        return Response(status_code=403)

    if event.event == "agent.message":
        print(f"SMS from {event.data.from_number}: {event.data.message}")

Error Handling

from agentphone import AgentPhoneError, AuthenticationError, NotFoundError

try:
    call = client.calls.get("bad-id")
except NotFoundError:
    print("Call not found")
except AgentPhoneError as e:
    print(f"API error {e.status}: {e.message}")

Publishing to PyPI

1. Install build tools (one-time):

   pip install hatch twine
   

2. Build the package:

   hatch build
   

   This creates a dist/ folder with the .tar.gz and .whl files.

3. Upload to PyPI:

   twine upload dist/*
   

   You'll be prompted for your PyPI credentials. To use an API token instead:

   twine upload dist/* -u __token__ -p pypi-your-token-here
   

4. Publishing a new version — bump the version in pyproject.toml first:

   version = "0.1.1"
   

   Then rebuild and upload:

   hatch build && twine upload dist/*
   

Requirements

• Python 3.9+
• requests (sync client)
• httpx (async client, optional)

Links

• AgentPhone Dashboard
• MCP Server
• Node.js SDK