> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentline.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create and configure AI voice agents.

# Agents

An **agent** bundles a system prompt, greeting, voice, and call-handling
behavior. Every number and call belongs to an agent.

JavaScript examples call `https://api.agentline.cloud` with `fetch` and a
Bearer `al_live_...` key. The Node package is not on npm.

## Create an agent

<CodeGroup>
  ```python theme={null}
  agent = client.agents.create(
      name="Support Bot",
      system_prompt="You are a helpful assistant. Be concise.",
      initial_greeting="Hi, this is Support. How can I help?",
      voice_id="female-1",
      voicemail_message="Hi, this is Support calling about your request. Please call us back at 555-0100.",
  )
  ```

  ```javascript theme={null}
  const agent = await fetch("https://api.agentline.cloud/v1/agents", {
    method: "POST",
    headers: {
      Authorization: "Bearer al_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Support Bot",
      system_prompt: "You are a helpful assistant. Be concise.",
      initial_greeting: "Hi, this is Support. How can I help?",
      voice_id: "female-1",
      voicemail_message: "Hi, this is Support calling about your request. Please call us back at 555-0100.",
    }),
  }).then((res) => res.json());
  ```
</CodeGroup>

| Field | Purpose |
| - | - |
| `name` | Display name |
| `system_prompt` | Default instructions for all calls |
| `initial_greeting` | Opening line spoken when a call connects |
| `voice_id` | TTS preset or Cartesia UUID. Presets: `female-1` (friendly), `female-2` (reassuring), `female-3` (guide), `male-1` (supportive), `male-2` (thinker), `male-3` (helpful) |
| `transfer_number` | Must be the owner's phone. A different number is rejected. Live transfers dial only `owner_phone`. |
| `voicemail_message` | Spoken message left on outbound voicemail. **Required** if the agent should leave a mailbox message; without it the agent hangs up. |
| `owner_phone` | Owner number in E.164. Calls from it enter task mode, and it is the only live-call transfer destination. Setting it also sets `transfer_number`. |

## Leaving voicemail

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

* **Greeting** — *"You've reached…"*, *"12418174 is not available"*, *"leave a message after the beep"*. The agent does **not** press keys. It waits for the beep, speaks the message, and hangs up.
* **Record-key menu** — *"To disconnect, press 1. To record your message, press 2."* The agent presses **2**, waits for the beep, then leaves the same message. If `voicemail_message` is unset it presses disconnect instead.

Include who you are, why you're calling, and a callback number. Do **not** add "stay silent on automated messages" or "hang up if you hear press 1" to the system prompt — that fights the built-in handler.

<CodeGroup>
  ```python theme={null}
  client.agents.update(
      agent.id,
      voicemail_message="Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
  )
  ```

  ```javascript theme={null}
  await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
    method: "PATCH",
    headers: {
      Authorization: "Bearer al_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      voicemail_message: "Hi, this is Alex calling about the apartment. Please call me back at 555-0100.",
    }),
  });
  ```
</CodeGroup>

## Manage agents

<CodeGroup>
  ```python theme={null}
  client.agents.list()
  client.agents.get(agent.id)
  client.agents.update(agent.id, voice_id="male-1")
  client.agents.delete(agent.id)
  ```

  ```javascript theme={null}
  const headers = { Authorization: "Bearer al_live_..." };

  await fetch("https://api.agentline.cloud/v1/agents", { headers });
  await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, { headers });
  await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
    method: "PATCH",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ voice_id: "male-1" }),
  });
  await fetch(`https://api.agentline.cloud/v1/agents/${agent.id}`, {
    method: "DELETE",
    headers,
  });
  ```
</CodeGroup>

<Tip>
  Per-call overrides: when making a call you can pass `system_prompt`,
  `initial_greeting`, and `voice_id` to override the agent defaults for that
  single call.
</Tip>

See the [Create Agent endpoint](/api-reference) in the API Reference.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.