Metadata-Version: 2.5
Name: agentsim-sdk
Version: 0.31.0
Summary: AgentSIM Python SDK — autonomous OTP relay for AI agents
Project-URL: Homepage, https://agentsim.dev
Project-URL: Repository, https://github.com/agentsim/agentsim
Project-URL: Documentation, https://agentsim.dev/docs
Project-URL: Changelog, https://github.com/agentsim/agentsim/blob/main/CHANGELOG.md
Author-email: AgentSIM <fathin@agentsim.dev>
License: MIT
Keywords: agents,ai,automation,otp,sms
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# agentsim-sdk

We run the auth challenge so your agent doesn't die there. This Python SDK opens an SMS challenge, waits for the verdict, and closes the session. Import name is `agentsim`. Primary names: `open_challenge` / `wait_for_verdict`. `provision` / `wait_for_otp` are aliases that still work. There is no `AgentSIM()` class.

**Availability:** The free Hobby plan includes 10 live US SMS sessions per month for apps you own, with one active live session per account and no card required. Sample demos do not use the allowance. The new paid live offer is not open yet; existing agreements remain unchanged. Check [current access and channel support](https://docs.agentsim.dev/availability) before using live examples.

## Install

```bash
uv add agentsim-sdk
```

Or with pip:

```bash
pip install agentsim-sdk
```

## Quickstart

Set `AGENTSIM_API_KEY` first. Run this inside an async function. Replace the target with an owned public HTTPS origin; `enter_phone_number` and `enter_otp` are your app automation callbacks. The first must request the SMS.

```python
import agentsim

async with agentsim.open_challenge(agent_id="checkout-bot", service_url="https://staging.example.com", country="US") as num:
    await enter_phone_number(num.number)
    otp = await num.wait_for_verdict(timeout=60)
    await enter_otp(otp.otp_code)
```

## Auth

Set `AGENTSIM_API_KEY` in your environment, or call `agentsim.configure()` at startup:

```python
agentsim.configure(api_key="asm_live_xxx")
```

Get your API key at [console.agentsim.dev](https://console.agentsim.dev).

## API

### `agentsim.open_challenge(*, agent_id, service_url, country="US", ttl_seconds=3600, webhook_url=None)`

Returns an async context manager. Opens an SMS challenge on enter, auto-releases on exit. `provision` is an alias.

```python
async with agentsim.open_challenge(agent_id="checkout-bot", service_url="https://staging.example.com", country="US") as num:
    print(num.number)
    print(num.session_id)
    otp = await num.wait_for_verdict(timeout=60)
    print(otp.otp_code)
```

### `num.wait_for_verdict(timeout=60, auto_reroute=False, max_reroutes=2, on_reregistration_needed=None)`

Long-polls until the SMS verdict arrives or `timeout` seconds elapse. `wait_for_otp` is an alias.

Returns: `OtpResult(otp_code, from_number, received_at)`

Raises: `OtpTimeoutError` if no verdict arrives within `timeout` seconds.

The shipped SDK does not include `wait_for_verdict_sync`. MCP agents should use `open_challenge` / `wait_for_verdict`.

## Error Reference

| Exception | When |
|-----------|------|
| `AuthenticationError` | Missing or invalid API key |
| `PoolExhaustedError` | No numbers available in requested country |
| `OtpTimeoutError` | No verdict arrived within `timeout` seconds |
| `RateLimitError` | Too many requests — back off and retry |
| `SessionNotFoundError` | Session expired or already released |

## Supported Countries

US
