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: Live SMS is self-serve for owned public HTTPS services after exact-origin verification and an allow policy. Hobby includes 10 live US SMS sessions per UTC month, with one active live session per account and no card required. Builder is $99/month and includes 50 live US SMS sessions. Checkout shows tax and renewal terms before payment, and existing agreements keep their terms. Check current access and channel support before using live examples.

Install

uv add agentsim-sdk

Or with pip:

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.

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:

agentsim.configure(api_key="asm_live_xxx")

Get your API key at 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.

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