Skip to content

Commit 0a87d85

Browse files
author
AgentSIM
committed
chore: sync from monorepo v0.10.0-sync-test
1 parent 159c605 commit 0a87d85

File tree

2 files changed

+44
-126
lines changed

2 files changed

+44
-126
lines changed

‎README.md‎

Lines changed: 38 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -1,169 +1,85 @@
1-
<p align="center">
2-
<a href="https://agentsim.dev">
3-
<img src="https://agentsim.dev/logo.svg" alt="AgentSIM" width="80" />
4-
</a>
5-
</p>
1+
# agentsim-sdk
62

7-
<h1 align="center">agentsim-sdk</h1>
8-
9-
<p align="center">
10-
<strong>Python SDK for AgentSIM — real SIM-backed phone numbers for AI agents</strong>
11-
</p>
12-
13-
<p align="center">
14-
<a href="https://pypi.org/project/agentsim-sdk/"><img src="https://img.shields.io/pypi/v/agentsim-sdk?color=%2334D058&label=pypi" alt="PyPI version"></a>
15-
<a href="https://pypi.org/project/agentsim-sdk/"><img src="https://img.shields.io/pypi/pyversions/agentsim-sdk" alt="Python versions"></a>
16-
<a href="https://github.com/agentsimdev/agentsim-python/blob/main/LICENSE"><img src="https://img.shields.io/github/license/agentsimdev/agentsim-python" alt="License"></a>
17-
</p>
18-
19-
<p align="center">
20-
<a href="https://docs.agentsim.dev">Docs</a> ·
21-
<a href="https://agentsim.dev/dashboard">Dashboard</a> ·
22-
<a href="https://github.com/agentsimdev/agentsim-examples">Examples</a> ·
23-
<a href="https://github.com/agentsimdev/agentsim-mcp">MCP Server</a>
24-
</p>
25-
26-
---
27-
28-
Provision real carrier-routed mobile numbers, receive inbound SMS, and get parsed OTP codes — all from your AI agent. No VoIP. No human relay. Carrier lookup returns `mobile`.
3+
Autonomous OTP relay for AI agents. AgentSIM provisions real carrier-routed phone numbers, receives inbound SMS, and delivers parsed OTP codes back to your agent — no human relay needed.
294

305
## Install
316

327
```bash
33-
pip install agentsim-sdk
8+
uv add agentsim-sdk
349
```
3510

36-
Or with [uv](https://docs.astral.sh/uv/):
11+
Or with pip:
3712

3813
```bash
39-
uv add agentsim-sdk
14+
pip install agentsim-sdk
4015
```
4116

42-
## Quick Start
17+
## Quickstart
4318

4419
```python
4520
import agentsim
4621

4722
async with agentsim.provision(agent_id="checkout-bot", country="US") as num:
48-
await enter_phone_number(num.number) # "+14155552671"
23+
await enter_phone_number(num.number) # "+14155552671"
4924
otp = await num.wait_for_otp(timeout=60)
50-
await enter_otp(otp.otp_code) # "391847"
25+
await enter_otp(otp.otp_code) # "391847"
5126
# number auto-released
5227
```
5328

54-
## Authentication
29+
## Auth
5530

56-
Set `AGENTSIM_API_KEY` in your environment, or call `configure()` at startup:
31+
Set `AGENTSIM_API_KEY` in your environment, or call `agentsim.configure()` at startup:
5732

5833
```python
5934
agentsim.configure(api_key="asm_live_xxx")
6035
```
6136

62-
Get your API key at [agentsim.dev/dashboard](https://agentsim.dev/dashboard).
63-
64-
## Usage
65-
66-
### Async (recommended)
67-
68-
```python
69-
import agentsim
37+
Get your API key at [console.agentsim.dev](https://console.agentsim.dev).
7038

71-
async with agentsim.provision(agent_id="signup-bot", country="US") as num:
72-
print(num.number) # E.164 phone number
73-
print(num.session_id) # session identifier
39+
## API
7440

75-
otp = await num.wait_for_otp(timeout=60)
76-
print(otp.otp_code) # "847291"
77-
```
41+
### `agentsim.provision(*, agent_id, country="US", service_url=None, ttl_seconds=3600, webhook_url=None)`
7842

79-
### Sync
43+
Returns an async context manager. Provisions a number on enter, auto-releases on exit (even if the body raises).
8044

8145
```python
82-
import agentsim
83-
84-
with agentsim.provision_sync(agent_id="checkout-bot") as num:
85-
otp = num.wait_for_otp_sync(timeout=60)
46+
async with agentsim.provision(agent_id="stripe-setup", country="US") as num:
47+
print(num.number) # E.164 phone number
48+
print(num.session_id)
49+
otp = await num.wait_for_otp(timeout=30)
8650
print(otp.otp_code)
8751
```
8852

89-
### Auto-reroute
90-
91-
If the first number doesn't receive an OTP (carrier cold-start filtering), automatically swap to a fresh number:
92-
93-
```python
94-
async with agentsim.provision(agent_id="resilient-bot") as num:
95-
otp = await num.wait_for_otp(
96-
timeout=60,
97-
auto_reroute=True,
98-
max_reroutes=2,
99-
on_reregistration_needed=handle_new_number,
100-
)
101-
```
102-
103-
## API Reference
53+
### `num.wait_for_otp(timeout=60, auto_reroute=False, max_reroutes=2, on_reregistration_needed=None)`
10454

105-
### `agentsim.provision()`
55+
Long-polls until an OTP arrives or `timeout` seconds elapse.
10656

107-
| Parameter | Type | Default | Description |
108-
|-----------|------|---------|-------------|
109-
| `agent_id` | `str` | required | Identifier for your agent |
110-
| `country` | `str` | `"US"` | ISO 3166-1 alpha-2 country code |
111-
| `ttl_seconds` | `int` | `3600` | Auto-release after N seconds |
112-
| `webhook_url` | `str` | `None` | Receive OTPs via webhook |
57+
Returns: `OtpResult(otp_code, from_number, received_at)`
11358

114-
Returns an async context manager. Provisions a number on enter, auto-releases on exit.
59+
Raises: `OtpTimeoutError` if no OTP arrives within `timeout` seconds.
11560

116-
### `num.wait_for_otp()`
61+
Set `auto_reroute=True` to automatically provision a replacement number in another country if no OTP arrives. `on_reregistration_needed` is an async callback `(new_number: str, country: str) -> None` called when re-registration on the target service is required.
11762

118-
| Parameter | Type | Default | Description |
119-
|-----------|------|---------|-------------|
120-
| `timeout` | `int` | `60` | Max seconds to wait |
121-
| `auto_reroute` | `bool` | `False` | Swap number on timeout |
122-
| `max_reroutes` | `int` | `2` | Max reroute attempts |
63+
### `agentsim.provision_sync(...)` / `num.wait_for_otp_sync(timeout=60)`
12364

124-
Returns `OtpResult(otp_code, from_number, received_at)`.
125-
126-
### `num.release()`
127-
128-
Release the number early. Called automatically when the context manager exits.
129-
130-
## Error Handling
65+
Synchronous variants for non-async codebases:
13166

13267
```python
133-
from agentsim import OtpTimeoutError, PoolExhaustedError
134-
135-
try:
136-
async with agentsim.provision(agent_id="my-bot") as num:
137-
otp = await num.wait_for_otp(timeout=30)
138-
except OtpTimeoutError:
139-
print("No OTP received — not billed")
140-
except PoolExhaustedError:
141-
print("No numbers available in this country")
68+
with agentsim.provision_sync(agent_id="x") as num:
69+
otp = num.wait_for_otp_sync(timeout=60)
14270
```
14371

144-
| Exception | HTTP | When |
145-
|-----------|------|------|
146-
| `AuthenticationError` | 401 | Missing or invalid API key |
147-
| `ForbiddenError` | 403 | Key revoked or lacking permissions |
148-
| `PoolExhaustedError` | 503 | No numbers available in requested country |
149-
| `OtpTimeoutError` | 408 | No OTP arrived within timeout (not billed) |
150-
| `RateLimitError` | 429 | Too many requests |
151-
| `SessionNotFoundError` | 404 | Session expired or already released |
152-
| `CountryNotAllowedError` | 403 | Country not on your plan |
153-
154-
## Pricing
155-
156-
- **Hobby**: 10 free sessions/month
157-
- **Builder**: $0.99/session
158-
- Sessions that time out (`OtpTimeoutError`) are **not billed**
159-
160-
## Links
72+
## Error Reference
16173

162-
- [Documentation](https://docs.agentsim.dev)
163-
- [TypeScript SDK](https://github.com/agentsimdev/agentsim-typescript)
164-
- [MCP Server](https://github.com/agentsimdev/agentsim-mcp)
165-
- [Examples](https://github.com/agentsimdev/agentsim-examples)
74+
| Exception | When |
75+
|-----------|------|
76+
| `AuthenticationError` | Missing or invalid API key |
77+
| `PoolExhaustedError` | No numbers available in requested country |
78+
| `OtpTimeoutError` | No OTP arrived within `timeout` seconds |
79+
| `RateLimitError` | Too many requests — back off and retry |
80+
| `SessionNotFoundError` | Session expired or already released |
81+
| `CountryNotAllowedError` | Country not available on current plan |
16682

167-
## License
83+
## Supported Countries
16884

169-
[MIT](LICENSE)
85+
US

‎pyproject.toml‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "agentsim-sdk"
3-
version = "0.9.0"
3+
version = "0.10.0"
44
description = "AgentSIM Python SDK — autonomous OTP relay for AI agents"
55
readme = "README.md"
66
requires-python = ">=3.11"
@@ -22,9 +22,9 @@ dependencies = [
2222

2323
[project.urls]
2424
Homepage = "https://agentsim.dev"
25-
Repository = "https://github.com/agentsimdev/agentsim-python"
26-
Documentation = "https://docs.agentsim.dev"
27-
Changelog = "https://github.com/agentsimdev/agentsim-python/blob/main/CHANGELOG.md"
25+
Repository = "https://github.com/agentsim/agentsim"
26+
Documentation = "https://agentsim.dev/docs"
27+
Changelog = "https://github.com/agentsim/agentsim/blob/main/CHANGELOG.md"
2828

2929
[project.optional-dependencies]
3030
dev = [
@@ -42,3 +42,5 @@ packages = ["agentsim"]
4242

4343
[tool.pytest.ini_options]
4444
asyncio_mode = "auto"
45+
46+
# sync-test: 2026-03-28T08:39:31Z

0 commit comments

Comments
 (0)