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

# Agents and variables

> Choose who calls, and fill their script with your data.

An **agent** is a configured AI caller: its voice, language, opening line, script, the questions it asks and the labels it can give a call. You create and edit agents in the dashboard (Settings → AI calling); the API chooses which one makes each call with `agent_id`.

## Listing agents

```bash theme={null}
curl https://api.telleo.ai/v1/agents -H "X-API-Key: $TELLEO_API_KEY"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
      "object": "agent",
      "name": "Riya – admissions",
      "language": "en-IN",
      "uses_contact_name": true,
      "variables": ["course", "city"]
    }
  ],
  "has_more": false
}
```

Only agents that are **turned on** and can **call out** are listed. Using one that is turned off returns `409 agent_disabled`; an inbound-only agent returns `409 agent_inbound_only`.

## Personalising the call

Agent scripts contain placeholders in double braces, such as:

> Hi {{name}}, this is Riya from Shiksha Academy. You enquired about {{course}} in {{city}} — is this a good time?

You fill them per call:

```json theme={null}
{
  "agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
  "phone_number": "+919876543210",
  "contact": { "name": "Asha Verma" },
  "variables": { "course": "NEET 2027", "city": "Indore" }
}
```

* **`{{name}}`** comes from `contact.name`. When `uses_contact_name` is `true`, always send it: an agent that does not know the name greets the person without it.
* **Everything else** comes from `variables`. The `variables` list on each agent shows exactly which keys its script uses.
* The agent also knows the current date and time on its own; you do not send those.

### Rules for variables

| | Limit |
| - | - |
| Number of variables | 50 per call |
| Key | Starts with a letter; letters, digits, `_` and spaces; up to 40 characters |
| Value | Text, a number or `true`/`false`; up to 500 characters |

Variables are spoken by the agent, so send them the way a person would say them: `"NEET 2027"`, not `"neet_2027_batch_b"`.

<Tip>
  Keep data the agent should **not** say in `metadata` instead. It is stored with the call and returned to you, but never shown to the agent.
</Tip>

## The contact

| Field | Purpose |
| - | - |
| `contact.name` | How the agent addresses the person (up to 120 characters). |
| `contact.email` | Stored with the call and returned to you. |
| `contact.external_id` | Your id for this person (CRM record id, lead id). Filter calls with `GET /v1/calls?external_id=`. |


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