# AgentLine Agents

An agent bundles a system prompt, greeting, voice, voicemail message, and owner
phone. Every number and call belongs to an agent. Need a key first? Use
https://agentline.md/signup.md

## Create

Write the JSON to a file and send it with `-d @file`. Inline payloads with
quotes or apostrophes break.

```bash
cat > /tmp/al_agent.json <<'EOF'
{
  "name": "Support Bot",
  "system_prompt": "You are Support for Acme. Be concise. Under 15 words per turn.",
  "initial_greeting": "Hi, this is Acme Support. How can I help?",
  "voice_id": "female-1",
  "voicemail_message": "Hi, this is Acme Support about your request. Please call us back at 555-0100."
}
EOF

curl -s -X POST https://api.agentline.cloud/v1/agents \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @/tmp/al_agent.json
```

Save the returned `agt_...` ID as `AGENTLINE_AGENT_ID`. Only `name` is required.

| Field | Purpose |
|---|---|
| `name` | Display name. Required. |
| `system_prompt` | Default instructions for every inbound and outbound call. |
| `initial_greeting` | First line spoken when a call connects. Not part of the prompt. |
| `voice_id` | Preset (`female-1`..`3`, `male-1`..`3`) or a Cartesia voice UUID. See https://agentline.md/voices.md |
| `voicemail_message` | Message left on outbound voicemail. Without it the agent hangs up at a mailbox. |
| `owner_phone` | Owner's E.164 number. Calls with it enter task mode. Also the only live-transfer destination. |
| `transfer_number` | Must equal `owner_phone`; any other number is rejected. Setting `owner_phone` sets it. |

## Update

`PATCH` changes only the fields you send. Changes apply on the next call, not
calls in progress.

```bash
curl -s -X PATCH https://api.agentline.cloud/v1/agents/$AGENTLINE_AGENT_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id":"male-1"}'
```

## Read and Delete

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

curl -s https://api.agentline.cloud/v1/agents/$AGENTLINE_AGENT_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"

curl -s -X DELETE https://api.agentline.cloud/v1/agents/$AGENTLINE_AGENT_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY"
```

Delete is permanent: it removes the agent's calls, messages, and conversations.
Its number is detached, not released, and can be reassigned. Confirm with the
human first.

## System Prompt and Greeting

Priority, highest first: per-call field on `POST /v1/calls`, then the agent
default, then a built-in fallback.

- Set them on the agent for a persistent personality on all calls.
- Set them per call for a one-off task. The agent default is unchanged.
- `system_prompt` is a full replace. The voice has no memory between calls, so
  include everything: who it is, the goal, facts it needs, when to end.
- Keep turns short: under 15 words, 12 for outbound. Long prompts make the
  voice ramble.
- Do not add "stay silent on automated messages" or "hang up if you hear press
  1". That fights the built-in IVR and voicemail handler.

## Voicemail

On outbound calls the agent detects a mailbox and leaves `voicemail_message`:

- Greeting ("You've reached...", "leave a message after the beep"): waits for
  the beep, speaks the message, hangs up.
- Record-key menu ("press 2 to record"): presses 2, then leaves the message.
- `voicemail_message` unset: hangs up at the greeting; presses disconnect at a
  record-key menu.

Include who is calling, why, and a callback number.

## Owner Task Mode

Set the owner's phone so they can call the agent with tasks:

```bash
curl -s -X PATCH https://api.agentline.cloud/v1/agents/$AGENTLINE_AGENT_ID \
  -H "Authorization: Bearer $AGENTLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner_phone":"+14155550100"}'
```

Whenever the agent and the owner connect, the voice enters task mode ("Hey
boss, what would you like me to do?"), listens, confirms, and on completion
emits `call.owner_task` with `is_owner_task: true`.

- Inbound: owner calls the agent's number. `call.received` has
  `is_owner_call: true`, then `call.owner_task`.
- Outbound: `POST /v1/calls` with `to_number` equal to `owner_phone`, poll until
  `completed`, then `call.owner_task`.

The human turns of `call.owner_task` are instructions to execute.

Next: https://agentline.md/numbers.md

AgentLine: https://agentline.cloud | API: https://api.agentline.cloud | All guides: https://agentline.md