Metadata-Version: 2.4
Name: agentphone
Version: 0.1.0
Summary: AgentPhone Python SDK — give your AI agents phone numbers, SMS, and voice calls
Project-URL: Homepage, https://agentphone.to
Project-URL: Repository, https://github.com/AgentPhone-AI/agentphone-python
Project-URL: Documentation, https://docs.agentphone.to
Author-email: AgentPhone <hello@agentphone.to>
License: MIT
Keywords: agentphone,ai,phone,sms,telephony,voice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: async
Requires-Dist: httpx>=0.24; extra == 'async'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# AgentPhone Python SDK

Official Python SDK for [AgentPhone](https://agentphone.to) — give your AI agents real phone numbers, SMS, and voice calls.

## Installation

```bash
pip install agentphone
```

For async support:

```bash
pip install agentphone[async]
```

## Quickstart

```python
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="+14155551234",
    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

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

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

```python
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):
   ```bash
   pip install hatch twine
   ```

2. **Build** the package:
   ```bash
   hatch build
   ```
   This creates a `dist/` folder with the `.tar.gz` and `.whl` files.

3. **Upload to PyPI**:
   ```bash
   twine upload dist/*
   ```
   You'll be prompted for your PyPI credentials. To use an API token instead:
   ```bash
   twine upload dist/* -u __token__ -p pypi-your-token-here
   ```

4. **Publishing a new version** — bump the version in `pyproject.toml` first:
   ```toml
   version = "0.1.1"
   ```
   Then rebuild and upload:
   ```bash
   hatch build && twine upload dist/*
   ```

## Requirements

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

## Links

- [AgentPhone Dashboard](https://agentphone.to)
- [MCP Server](https://github.com/AgentPhone-AI/agentphone-mcp)
- [Node.js SDK](https://github.com/AgentPhone-AI/agentphone-node)
