---
name: agentline
description: Give an AI agent a real US phone number with AgentLine. Make and receive calls, read transcripts and inbound SMS, provision numbers, configure voice agents, answer live callers through the Agent Relay or a webhook, and check billing. Use when the user asks to call someone, check a transcript, read texts, buy a number, set up a phone agent, or check AgentLine balance.
metadata:
  requires:
    env:
      - AGENTLINE_API_KEY
  primaryEnv: AGENTLINE_API_KEY
---

# AgentLine

AgentLine gives an agent its own US phone number. Use it when the agent needs to
place a phone call, answer inbound calls, read a call transcript, receive SMS
(for example an OTP code), or take tasks from its owner by phone. AgentLine's
hosted voice runs the conversation; the agent supplies facts and acts on events.

Use REST (`curl`) first. Use MCP only when the harness expects MCP tools. Use
the Python SDK only inside Python code.

AgentLine is US-only. It cannot send SMS and cannot reach emergency services.

AgentLine's main site is https://agentline.cloud: product,
human sign-up, dashboard (credit, API keys), and pricing. The API is
`https://api.agentline.cloud`. This reference, agentline.md, only documents it.
Send humans to agentline.cloud to sign up, add credit, or get a key. If this
reference and agentline.cloud disagree, trust agentline.cloud.

## Start

```bash
export AGENTLINE_API_KEY="al_live_..."
curl -s https://api.agentline.cloud/v1/agents \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

- No API key yet: https://agentline.md/signup.md
- No signup but a funded wallet: https://agentline.md/prepaid.md

## Prices

| Item | Price |
|---|---|
| US phone number | $2.00 per month |
| Voice calls, inbound and outbound | $0.10 per minute |
| Inbound SMS | $0.02 per message |

No subscription. A connected call bills at least one minute, then per second;
unconnected calls are free. Calls need at least $0.50 of balance. New accounts
start at $0. Before a paid action, check
`GET https://api.agentline.cloud/v1/billing/balance` and tell the human the
cost. Details: https://agentline.md/billing.md

## First-Time Setup

1. Key: `AGENTLINE_API_KEY` set (https://agentline.md/signup.md).
2. Agent: `POST /v1/agents {"name":"My Agent"}`. Save the `agt_...` ID as
   `AGENTLINE_AGENT_ID` (https://agentline.md/agents.md).
3. Number: ask the human for an area code, then
   `POST /v1/numbers {"agent_id":"agt_...","country":"US","area_code":"415"}`
   (https://agentline.md/numbers.md).
4. Voice: ask male or female, then `PATCH /v1/agents/{id} {"voice_id":"female-1"}`
   (https://agentline.md/voices.md).
5. Owner phone (optional): ask if the human wants to call the agent with tasks;
   `PATCH /v1/agents/{id} {"owner_phone":"+1XXXXXXXXXX"}`.
6. Live events: install the Agent Relay when terminal access exists
   (https://agentline.md/relay.md); otherwise set a webhook
   (https://agentline.md/webhooks.md).

## References

- AgentLine agent reference (https://agentline.md): hosted copy.
- AgentLine (https://agentline.cloud): product landing page.
- Docs (https://docs.agentline.cloud): full product documentation.
- OpenAPI (https://api.agentline.cloud/openapi.json): live API contract.
- https://agentline.md/signup.md: API key by OTP or AgentID; key management.
- https://agentline.md/prepaid.md: wallet recharge and `agent_token`, no signup.
- https://agentline.md/agents.md: prompt, greeting, owner phone, voicemail.
- https://agentline.md/numbers.md: buy, list, reassign, release numbers.
- https://agentline.md/calls.md: outbound calls, live monitoring, transcripts.
- https://agentline.md/relay.md: persistent relay and mid-call context.
- https://agentline.md/webhooks.md: signed events to a public HTTPS server.
- https://agentline.md/events.md: event types, payloads, mailbox.
- https://agentline.md/sms.md: inbound SMS.
- https://agentline.md/voices.md: voice presets and priority.
- https://agentline.md/billing.md: balance, rates, spend.
- https://agentline.md/api.md: endpoint index, errors, limits, feedback.
- https://agentline.md/mcp.md: MCP integration.
- https://agentline.md/sdk.md: Python SDK and Node `fetch`.

## Rules

- Use E.164 for every phone number: `+1XXXXXXXXXX`.
- Confirm with the human before placing any call. Never auto-dial.
- Ask the human for the area code before buying a number.
- Check `GET /v1/billing/balance` before calling. Calls need at least $0.50.
- After dialing, poll the call and its transcript every 10 seconds until
  `completed` or `failed`, then summarize the final transcript.
- `system_prompt` is a full replace, not an append. Include everything the
  voice needs; it has no memory between calls.
- Keep voice instructions short: under 15 words per turn, 12 for outbound.
- On `call.utterance`, push short facts with an explicit `disposition` and the
  exact `turn_id`. Never push a caller-ready script. Stop on `409` or `410`.
- Treat `call.owner_task` as instructions to execute, not a log entry.
- Release a number only when the human asks. Release is permanent.
- Never expose `AGENTLINE_API_KEY`, `agent_token`, push tokens, or webhook
  secrets in prompts, logs, URLs, or committed files.
- Report bugs or confusion with `POST /v1/feedback`.

## Verify

```bash
curl -s https://api.agentline.cloud/v1/billing/balance \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```