From zero to a live test call in about 5 minutes — using MCP, REST, or the CLI. Create an agent, publish it, and dial your own phone.

Quickstart

Goal: a published voice agent that calls your own phone, in about 5 minutes.

Before you start

Sign up at app.agoralia.app and pick a plan (the Free plan and its welcome credit are enough).
Make sure you have at least one phone number to call from (buy from the pool or link a BYO number) and your own phone number in E.164 format (e.g. +39...) to call to.
Pick a surface below and set up auth — see Authentication.

Pick your surface

1. Connect

claude mcp add --transport http agoralia https://api.agoralia.app/mcp

Approve the OAuth scopes when prompted. See MCP.

2. Create and publish an agent

Ask your MCP client to run the tools:

create_agent(
  name="Quickstart agent",
  language="en",
  system_prompt="You are a friendly Agoralia demo agent. Greet the caller, ask one question, and keep replies short."
)

publish_agent(agent_id="<AGENT_ID>")

3. Place the call

test_agent(
  agent_id="<AGENT_ID>",
  phone_number="<YOUR_PHONE_E164>",
  phone_number_id="<FROM_NUMBER_ID>"
)

The REST happy path is create agent → publish → place call. Base URL: https://api.agoralia.app/api/v1. Create an ag_... key in Dashboard → API Keys and send it in the X-API-Key header.

1. Create an agent

curl -X POST https://api.agoralia.app/api/v1/agents \
  -H "X-API-Key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart agent",
    "language": "en",
    "system_prompt": "You are a friendly Agoralia demo agent. Greet the caller, ask one question, and keep replies short."
  }'

The response includes the new agent's id.

2. Publish the agent

Publishing syncs the agent to the voice provider. It is required — a freshly created agent has no provider id and cannot place calls until published.

curl -X POST https://api.agoralia.app/api/v1/agents/<AGENT_ID>/publish \
  -H "X-API-Key: ag_your_key_here"

3. Place the call

curl -X POST https://api.agoralia.app/api/v1/calls \
  -H "X-API-Key: ag_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+39...",
    "agent_id": "<AGENT_ID>",
    "phone_number_id": "<FROM_NUMBER_ID>"
  }'

You get back { "call_id": ..., "status": "ringing", ... }. Your phone rings.

Mutating endpoints accept an Idempotency-Key header so retries don't create duplicates.

1. Authenticate

Mint a CLI token in Dashboard → API Keys → "CLI token", then log in (the default URL is production):

agoralia auth login --token <TOKEN>

Install the CLI with pip install agoralia-cli.

See CLI.

The CLI talks to the gated API via the generic call command — agoralia call <METHOD> <path> --data <json>.

2. Create and publish an agent

agoralia call POST /agents --data '{"name":"Quickstart agent","language":"en","system_prompt":"You are a friendly Agoralia demo agent. Greet the caller, ask one question, and keep replies short."}'

agoralia call POST /agents/<AGENT_ID>/publish

3. Place the call

agoralia call POST /calls --data '{"to_number":"+39...","agent_id":"<AGENT_ID>","phone_number_id":"<FROM_NUMBER_ID>"}'

After your first call

Inspect the call (transcript, summary, analysis) — see API endpoints.
Refine the system_prompt, then publish again so changes take effect.
Scale up to a campaign — launching requires a human approval and a compliance pass for the target countries.

Placing live calls is a risk-tiered action. In test mode you dial your own verified number; for real campaigns the gate requires a human "go" and a compliance pass.

Hit a snag?

See Troubleshooting for the common errors (401/422, "agent not synced", 429 rate limits, and more).

Quickstart

On this page