agentsim-sdk

AgentSIM is the control plane for agents hitting the real world's auth walls. SMS OTP is the first challenge type. This SDK provisions a US test number, waits for the parsed code, and releases the session. Local mock mode accepts inbound messages through the REST API.

Install

uv add agentsim-sdk

Or with pip:

pip install agentsim-sdk

Quickstart

import agentsim

async with agentsim.provision(agent_id="checkout-bot", country="US") as num:
    await enter_phone_number(num.number)          # "+12025550142"
    otp = await num.wait_for_otp(timeout=60)
    await enter_otp(otp.otp_code)                 # "391847"
# number auto-released

Auth

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

agentsim.configure(api_key="asm_live_xxx")

Get your API key at console.agentsim.dev.

API

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

Returns an async context manager. Provisions a number on enter, auto-releases on exit (even if the body raises).

async with agentsim.provision(agent_id="checkout-bot", country="US") as num:
    print(num.number)   # E.164 phone number
    print(num.session_id)
    otp = await num.wait_for_otp(timeout=30)
    print(otp.otp_code)

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

Long-polls until an OTP arrives or timeout seconds elapse.

Returns: OtpResult(otp_code, from_number, received_at)

Raises: OtpTimeoutError if no OTP arrives within timeout seconds.

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.

`agentsim.provision_sync(...)` / `num.wait_for_otp_sync(timeout=60)`

Synchronous variants for non-async codebases:

with agentsim.provision_sync(agent_id="x") as num:
    otp = num.wait_for_otp_sync(timeout=60)

Error Reference

Exception	When
`AuthenticationError`	Missing or invalid API key
`PoolExhaustedError`	No numbers available in requested country
`OtpTimeoutError`	No OTP arrived within `timeout` seconds
`RateLimitError`	Too many requests — back off and retry
`SessionNotFoundError`	Session expired or already released
`CountryNotAllowedError`	Country not available on current plan

Supported Countries

Development Status
- 3 - Alpha
Intended Audience
- Developers
Programming Language
- Python :: 3.11
- Python :: 3.12

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

agentsim_sdk-0.22.0.tar.gz (22.2 kB view details)

Uploaded Aug 24, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

agentsim_sdk-0.22.0-py3-none-any.whl (8.1 kB view details)

Uploaded Aug 24, 2026 Python 3

File details

Details for the file agentsim_sdk-0.22.0.tar.gz.

File metadata

Download URL: agentsim_sdk-0.22.0.tar.gz
Upload date: Aug 24, 2026
Size: 22.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for agentsim_sdk-0.22.0.tar.gz
Algorithm	Hash digest
SHA256	`1df5e8b1e6c30418bc9149af12bc8b91e19532c4f022bbbfc190acd813eb64a6`
MD5	`f7227d750d5c0c4d54c6f462b1fa3a74`
BLAKE2b-256	`6cfc5fbbd80daef09ff32bc7baf172222898fe29f89eecafeabcc16c219a5caa`

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentsim_sdk-0.22.0.tar.gz:

Publisher: publish-pypi.yml on agentsimdev/agentsim

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: agentsim_sdk-0.22.0.tar.gz
- Subject digest: 1df5e8b1e6c30418bc9149af12bc8b91e19532c4f022bbbfc190acd813eb64a6
- Sigstore transparency entry: 2582033775
- Sigstore integration time: Aug 24, 2026
Source repository:
- Permalink: agentsimdev/agentsim@7e28a1597020d53d2fa54c9e88ea89b909316a12
- Branch / Tag: refs/tags/v0.22.0
- Owner: https://github.com/agentsimdev
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-pypi.yml@7e28a1597020d53d2fa54c9e88ea89b909316a12
- Trigger Event: release