# AgentSIM

> AgentSIM is the control plane for agents hitting the real world's auth walls. SMS OTP is the first challenge type.

Connector 0 provisions a synthetic or programmable US test number, waits for or accepts an injected SMS, runs the OTP parser, records the outcome, and releases the session. Agents can use it through SDKs, REST, webhooks, or MCP. One session is one number provisioned, one OTP attempt, one observed outcome, and one release. The Builder plan costs $0.99 per session.

## Authorized Use Only

AgentSIM is for **authorized testing of systems you own or are permitted to test** and for OTP workflows on auth providers you control. Connector 0 uses synthetic or programmable US test numbers.

**Built for:**
- Browser agents that hit SMS OTP in an owned or controlled flow
- CI pipelines that test SMS OTP delivery and parsing
- Controlled staging environments and owned auth providers

**Not for:**
- Creating accounts on third-party services you do not own
- Bypassing anti-abuse systems at Google, Meta, Stripe, or banks
- Bulk account creation or ban evasion on consumer platforms
- Any use that violates the target service's terms or applicable law
- Replacing a long-lived recovery number for a persistent identity

## Where AgentSIM Works (Today)

**Do not assume support by default.** The empirical support map lives in the open-source repo at docs/supported-services.md.

Current hard evidence: Google rejects the current number class. Meta/Facebook mobile reaches SMS code entry but delivery is unproven. Telegram accepts the phone field but did not exercise/prove SMS delivery. Stripe, Render, Discord, and GitHub hit anti-abuse gates before a phone verdict in blind automation. Auth0's self-serve flow is email-first and not a useful OTP proof target.

If you are testing a strict or high-risk target, verify it first; AgentSIM may not be the right tool today.

Built for developers running browser agents, QA suites, and controlled auth workflows where the target service is owned by you or empirically known to accept programmable US numbers.

Dedicated use-case pages:
- Browser-Agent OTP QA: https://agentsim.dev/use-cases/browser-agent-otp-qa
- Fraud & Security Testing: https://agentsim.dev/use-cases/fraud-testing


## How It Works

The happy path provisions a number, waits for SMS, returns the parsed code, and releases the session. Delivery diagnostics record what happened when the target does not send SMS.

### Step 01 — Provision (212ms)

```typescript
import { provision } from "@agentsim/sdk";

const session = await provision({
  agentId: "browser-agent-otp",
  country: "US",
  serviceUrl: "https://staging.example.com/login",
});
// session.number → "+12025550142"
// session.country → "US"
```

### Step 02 — Enter (88ms)

```typescript
await browser.fill(
  "input[name='phone']",
  session.number
);
await browser.click("button[type='submit']");
```

### Step 03 — Receive OTP (3.5s)

```typescript
const otp = await session.waitForOtp({
  timeout: 30_000,
});
// otp.otpCode → "847291"
await browser.fill("input[name='otp']", otp.otpCode);
```

### Execution Trace

| Time     | Operation              | Latency |
|----------|------------------------|---------|
| 00:00.0  | provision()            | 212ms   |
| 00:00.2  | browser.fill()         | 88ms    |
| 00:00.3  | service submits SMS    | varies  |
| 00:03.8  | session.waitForOtp()   | if SMS arrives |


## Features

### Synthetic or programmable US test numbers
Mock mode creates a synthetic US test number without purchased inventory. Provider-backed mode leases a programmable US test number from a managed pool and returns it to cooldown after release.

### OTP parsing built in
Raw SMS arrives: code extracted, service detected, structured JSON returned. No regex on your side.

### Per-agent scoping
Isolated number per agent_id. Auto-rotation if flagged. Cost tracked per agent.

### MCP-native
Ships as MCP server day one. Native tool calls in Claude Code, Cursor, Windsurf.

### Webhook + polling
Streaming webhook for real-time flows. Polling fallback for async tasks.

### Zero human assumptions
No CAPTCHA setup. API-key auth. Agent accounts. Programmatic billing.


## Use Cases

SMS OTP is the first challenge type in the AgentSIM control plane.

The primary use case is browser-agent OTP QA. AgentSIM gives a browser-agent run a temporary US test number, parses the OTP when SMS arrives, and records a delivery outcome when it does not, so the run can continue without a human watching an inbox.

Fraud and security testing remains a separate use-case page for authorized testing of systems you own or are permitted to test. It is not the primary product position.

Best fits:
- browser-agent QA against owned apps or staging tenants
- Playwright, Browserbase, Stagehand, Selenium, or custom browser-agent tests
- controlled auth providers such as Supabase, Auth0, Firebase, or custom SMS auth when credentials and test tenants are available
- services with dated evidence that the current number class works

Not the promise:
- universal Google, Meta, Stripe, WhatsApp, bank, or crypto verification
- creating accounts on third-party services you do not own
- bulk account creation, ban evasion, or bypassing third-party anti-abuse systems
- assuming every service sends SMS to programmable numbers

Number-class context: https://docs.agentsim.dev/why-not-twilio


## Integrations

AgentSIM works where agents run. Use it from Claude Code, Cursor, Windsurf, LangChain, LlamaIndex, Vercel AI SDK, Playwright, or a custom browser-agent harness through MCP, SDKs, REST, or webhooks.

Live docs:
- Quickstart: https://docs.agentsim.dev/quickstart
- Concepts: https://docs.agentsim.dev/concepts
- Authentication: https://docs.agentsim.dev/authentication
- API reference: https://docs.agentsim.dev/api-reference/overview
- MCP setup: https://docs.agentsim.dev/mcp/connect
- MCP tools: https://docs.agentsim.dev/mcp/tools
- Public SKILL.md: https://agentsim.dev/.well-known/agent-skills/otp-sessions/SKILL.md
- Agent landing page: https://agentsim.dev/agents — auth.md registration, scoped bearer tokens, JWT refresh, and revocation for agents

These are integration targets, not blanket support claims. Destination service support remains empirical.


## Pricing

Pay per session. Not per number per month.

### Hobby — $0/forever
- 10 sessions / month
- 1 number per session
- US numbers
- MCP + SDK access

### Builder — $0.99/session (no monthly fee) [Most popular]
For agent teams testing and running OTP workflows.
- Unlimited sessions
- Parallel provisioning
- US numbers (more countries soon)
- OTP parsing built in
- Webhook + polling

### Enterprise — Custom pricing
dedicated pools · SLAs · SOC 2
- Dedicated number pools
- Custom carrier agreements
- SOC 2 / audit logs
- SLA support


## Comparison

AgentSIM vs JoltSMS vs cloud phone APIs vs shared virtual numbers.

| Decision point     | AgentSIM                                  | JoltSMS                         | Cloud phone APIs              | Shared virtual      |
|--------------------|-------------------------------------------|---------------------------------|-------------------------------|---------------------|
| Best fit           | Browser-agent OTP sessions + diagnostics | Persistent per-account identity | Programmable messaging        | Manual one-off tests|
| Number type        | Synthetic or programmable US test number  | Dedicated US number             | VoIP or cloud-routed number   | Recycled inventory  |
| Billing model      | $0.99/session after free tier             | $50/number/month                | Number rental + usage fees    | Dynamic per-code    |
| Agent delivery     | SDKs, REST, webhooks, polling, MCP        | REST, webhooks, MCP             | SMS webhooks + lookup APIs    | Usually inbox-first |
| OTP payload        | Parsed OTP plus raw message               | Parsed OTP plus raw message     | Usually raw inbound SMS       | Varies by marketplace|
| AgentSIM advantage | Controlled auth and verified-compatible OTP workflows | Better for long-lived re-verification | Better for normal SMS products | Better for throwaway manual checks |

100 paid AgentSIM sessions = $99. 100 dedicated JoltSMS numbers = $5,000/month.


## FAQ

### What exactly is a "session"?
One session = provision a temporary number for one OTP attempt, wait for delivery, record the outcome, and release it. You're billed once per provision call after the free tier. If your agent needs to test 3 OTP workflows, that's 3 sessions ($2.97). No monthly numbers sitting idle.

### What countries are supported?
US numbers today. Acceptance is service-specific; strict consumer platforms may reject or silently drop programmable numbers. More countries are a future option.

### How is this different from JoltSMS?
JoltSMS-style dedicated rentals are useful for persistent identity on a single account. AgentSIM charges per session and is built for short controlled-auth, QA, and verified-compatible OTP workflows where you do not want monthly idle inventory.

### Can I provision multiple numbers in parallel?
Yes. Each session is isolated. Provision as many in parallel as your plan allows. The Builder plan supports unlimited concurrent sessions.

### What if the OTP doesn't arrive?
wait_for_otp(timeout=30) throws a TimeoutError. Handle the retry in your agent. AgentSIM records session outcomes so you can distinguish OTP received, no SMS, timeout, and parsing failures instead of waiting silently.

### How is this different from raw Twilio/Vonage/Plivo?
Three differences: (1) AgentSIM is built for AI agents, with SDKs, an MCP server, and per-session billing instead of monthly number rentals; (2) the OTP parser returns structured codes instead of raw SMS bodies you have to parse; (3) account-isolated diagnostics show which destinations succeed and which reject the test numbers. Connector 0 uses synthetic or programmable US test numbers.


## MCP Setup

AgentSIM exposes its core primitives as MCP tools. One command. No SDK installation required.

### Claude Code setup

```shell
claude mcp add agentsim -e AGENTSIM_API_KEY=asm_live_xxx -- uvx agentsim-mcp
```

### JSON config (Cursor, Windsurf, others)

```json
{
  "mcpServers": {
    "agentsim": {
      "command": "uvx",
      "args": ["agentsim-mcp"],
      "env": {
        "AGENTSIM_API_KEY": "asm_live_..."
      }
    }
  }
}
```

### MCP Tools

**provision_number** — Lease a synthetic or programmable US test number for an agent session. Optionally pass service_url to label the destination in your diagnostics.
- agent_id: string
- country?: string
- ttl_seconds?: number
- service_url?: string
- Returns: { session_id, number }

**wait_for_otp** — Block until an SMS OTP arrives on the session. Returns the parsed code.
- session_id: string
- timeout_seconds?: number
- Returns: { otp_code, from_number, received_at }

**get_messages** — Return the raw inbound SMS messages for a session. Use this for diagnostics when no OTP is parsed, to classify the outcome (no_sms, sms_no_otp, phone_rejected, anti_bot_gate).
- session_id: string
- Returns: { messages: [{ from_number, body, received_at }] }

**list_numbers** — List the numbers currently leased to your account and their session state.
- Returns: { numbers: [{ session_id, number, status }] }

**release_number** — Close the session. Provider-backed numbers return to the pool.
- session_id: string
- Returns: { status }


## Blog

Technical articles on AI agents, phone verification, and SMS infrastructure. Posts explain how carrier lookup and VoIP classification work and where programmable numbers fit. Connector 0 uses synthetic or programmable US test numbers for flows you own, CI/QA, browser-agent testing, and verified-compatible targets. Programmable numbers are not mobile-classified and are not the right tool for strict consumer-platform signups (Stripe, Google, WhatsApp, etc.).

- [Blog Index](https://agentsim.dev/blog): Updated post index


## Links

- Homepage: https://agentsim.dev
- Blog: https://agentsim.dev/blog
- API Reference: https://docs.agentsim.dev/api-reference/overview
- Integrations: https://agentsim.dev/#integrations
- Quickstart Docs: https://docs.agentsim.dev/quickstart
- Agent Skill: https://agentsim.dev/.well-known/agent-skills/otp-sessions/SKILL.md
- Browser-Agent OTP QA: https://agentsim.dev/use-cases/browser-agent-otp-qa
- Fraud & Security Testing: https://agentsim.dev/use-cases/fraud-testing
- Support Evidence: https://agentsim.dev/use-cases/browser-agent-otp-qa#delivery-truth
- Number Limits: https://docs.agentsim.dev/why-not-twilio
- TypeScript SDK: https://docs.agentsim.dev/sdk/typescript
- Python SDK: https://docs.agentsim.dev/sdk/python
- MCP Server docs: https://docs.agentsim.dev/mcp/connect
- Sign up: https://agentsim.dev/sign-up
- X / Twitter: https://x.com/agentsimdev
- LinkedIn: https://www.linkedin.com/company/agentsim/
- Privacy Policy: https://agentsim.dev/privacy
- Terms of Service: https://agentsim.dev/terms
- Cookie Policy: https://agentsim.dev/cookies