provision_number
Lease a real mobile phone number for receiving SMS OTP codes.
Returns the phone number (e164 format) and a session_id needed for all
subsequent calls. The number is exclusively yours for ttl_seconds.
Next step: use the returned `number` on your target service to trigger an SMS,
then call `wait_for_otp` with the returned `session_id`.
wait_for_otp
Block until an SMS OTP arrives for this session, then return the code.
Polls the AgentSIM API for up to `timeout_seconds`. Returns the OTP code
and the message it was extracted from.
If the OTP does not arrive in time, raises a ToolError with advice on retrying.
Always call `release_number` after you have used the OTP.
get_messages
List all SMS messages received in this session without consuming the OTP.
Use this to inspect raw messages or check if an SMS arrived before calling
wait_for_otp. Does NOT mark the OTP as consumed.
release_number
Release a provisioned number back to the pool.
Always call this when you are done with the session — even on error —
to avoid consuming pool capacity unnecessarily.
list_numbers
List active sessions, optionally filtered by agent_id.
Use this to check for leaked sessions or inspect what numbers are
currently active in your account.