Guides

Creating and preparing agents

Console only

Agents are created, configured and published in the RelationsAI console. Through the API you read your agents and check whether each one is ready to place calls. This guide covers both halves so your integration only dials with an agent that can actually call.

By the end you will have the agent_... id to use in calls and campaigns, and a readiness check you can run before every batch of calls or as part of a deploy.

Before you begin

You need	Why
Access to the RelationsAI console as a member who can edit agents	Agents are built and published there
An API key with `agents:read`	To list agents and check readiness (every new key has it by default)
A test key (`rai_test_...`) to start with	Test mode has a built-in Sample agent, so you can follow this guide before your own agent is ready

Build the agent in the console

An agent is what the person you call hears: its instructions, voice, language and goal. In the console:

Create the agent and write its instructions. The instructions must tell the people the agent calls that they are speaking with an AI: an agent without that disclosure cannot be published. Put it at the start, so it is the first thing callers hear.
Choose a voice, language and call settings, and configure the fields you want extracted from each conversation and the goal the call should achieve. These become the analysis results of each call.
Assign a phone number for outbound calls. A call shows this number to the person called. Numbers are added and assigned in the console.
Publish the agent and switch it on. Calls always use the agent's published version. Editing a draft does not change calls until you publish again.

In test mode the Sample agent (agent_1ZltiWzxrXmMprGD6q63) and the sample number +12025550150 are always available and always ready, so every example in these guides works with a brand-new workspace. They do not exist in live mode. See Test mode.

List agents from the API

GET/agents returns your agents, newest first. Agents are shared configuration: a test key and a live key see the same agents (plus the Sample agent in test mode).

curl -X GET "https://voice-api.relationsai.com/v1/agents?limit=100" \
     -H "Authorization: Bearer <token>"

Response 200 (one agent shown):

JSON
{
  "object": "list",
  "data": [
    {
      "id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
      "object": "agent",
      "livemode": false,
      "name": "Loan renewal reminder",
      "description": "Reminds customers that their loan is due for renewal and books a callback.",
      "status": "active",
      "published": true,
      "published_version": 4,
      "is_default": true,
      "sample": false,
      "created_at": "2026-09-02T10:12:44.000Z",
      "updated_at": "2026-10-18T14:03:10.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Complete runnable example

List the agents in your workspace.

The same steps as a complete script, with error handling, tested against test mode on every docs build. Each script reads your test key from an environment variable named in its first lines.

cURL script (bash) list-agents.sh
JavaScript (Node.js 20+) list-agents.mjs
Python 3.9+ (requests) list-agents.py

What the fields mean:

Field	Meaning
`status`	`active` agents are switched on. `paused` and `draft` agents cannot place calls. Open enum: treat any other value as "not callable".
`published`	`true` when the agent has a published version. `null` means the publication state could not be read right now: use the readiness check for a definite answer.
`published_version`	The version calls use, when known.
`is_default`	The workspace's default agent in the console. The API never picks an agent for you: `agent_id` is always required when you place a call.
`sample`	`true` only for the built-in Sample agent in test mode.

To read one agent, use GET/agents/{agent_id}.

Check readiness

GET/agents/{agent_id}/readiness checks, right now, everything about the agent and the workspace that would stop a call, and returns every problem found rather than the first one. The example exits with status 1 when the agent is not ready, so you can use it as a gate in a deploy or before a batch job.

curl -X GET https://voice-api.relationsai.com/v1/agents/agent_1ZltiWzxrXmMprGD6q63/readiness \
     -H "Authorization: Bearer <token>"

Complete runnable example

Check that an agent can place calls. Exits 1 when it is not ready.

The same steps as a complete script, with error handling, tested against test mode on every docs build. Each script reads your test key from an environment variable named in its first lines.

cURL script (bash) check-readiness.sh
JavaScript (Node.js 20+) check-readiness.mjs
Python 3.9+ (requests) check-readiness.py

A ready agent returns 200 with an empty reasons list:

JSON
{
  "object": "agent_readiness",
  "livemode": true,
  "agent_id": "agent_3hT9kQ2mVx7RbN4pLc8Wz1",
  "ready": true,
  "reasons": [],
  "checked_at": "2026-10-21T09:30:00.000Z"
}

An agent that is not ready also returns 200, with ready: false and one entry per problem:

JSON
{
  "object": "agent_readiness",
  "livemode": true,
  "agent_id": "agent_7Yx2Wq9Lp4Mn8Bv3Kc6Hd1",
  "ready": false,
  "reasons": [
    { "code": "agent_not_published", "message": "Publish the agent in the console before placing calls." },
    { "code": "no_outbound_number", "message": "Assign a phone number to this agent for outbound calls in the console." }
  ],
  "checked_at": "2026-10-21T09:30:00.000Z"
}

Each reason code and what a console admin does about it:

`reasons[].code`	Meaning	Fix in the console
`agent_paused`	The agent is switched off	Switch the agent on
`agent_not_connected`	The agent has not been saved for calling yet	Save the agent; if the reason stays, contact support
`agent_not_published`	No published version, or its live version is paused	Publish the agent
`no_outbound_number`	No phone number is assigned to this agent for outbound calls	Assign an outbound number
`calling_not_configured`	The workspace has no telephony account or no number	Finish calling setup (Numbers)
`telephony_disconnected`	The workspace's telephony connection is not working	Reconnect the telephony account
`account_inactive`	The trial ended or the account is suspended	Upgrade, or contact support
`spend_limit_reached`	The monthly spend limit set by an admin is reached	Raise the limit
`insufficient_balance`	The balance is too low to start a call	Top up the balance

The list is an open enum: show message to an operator for codes you do not recognise. Never parse message.

In test mode the Sample agent is always ready. Your own agents are checked for configuration reasons only (agent and calling setup); balance, spend and account checks apply in live mode.

Configuring agents through the API

Planned Creating, editing and publishing agents through the API is planned for a later version. Today the workspace's capabilities.agent_editing (from GET/workspace) is false; check it rather than assuming. Until then, keep agent changes in the console and treat the API's agent list as read-only configuration.

What can go wrong

Placing a call with an agent that cannot call: agent_not_ready (422). details.reasons uses the readiness codes above. Fix the agent in the console, then send the same request again (nothing was dialled).
The agent id is unknown, malformed, from another workspace, or the Sample agent with a live key: resource_not_found (404). Use an id from GET /agents with a key of the same workspace and mode.
The agent has several outbound numbers: phone_number_required (422). Send phone_number_id with the call, or leave one outbound number on the agent.
The key lacks agents:read: insufficient_scope (403). Ask an admin for a key with agents:read.

Next steps

Making an outbound call with the agent you just checked.
GET/phone-numbers to choose a caller number for phone_number_id.

API availability Making an outbound call