Create, configure (system_prompt, language, voice) and publish a voice agent through MCP, REST, or the CLI. Publishing is required before an agent can place a call.

Agents

A voice agent is a few fields — a name, a system_prompt (its character and mission), a language, and a voice. Everything else has sane defaults. You build agents programmatically: there is no config wizard, and the same gated core (RBAC, compliance, pre-flight, budget) runs no matter which surface you use.

Happy path

Create → Publish → Call. A freshly created agent has no provider id yet, so POST /agents/{id}/publish is required before it can place a call. Skipping it returns 422 Agent not synced.

The agent model

Field	Required	What it is
`name`	yes	Internal label, 1–200 chars (e.g. `"Inbound — Support EN"`).
`system_prompt`	yes	The agent's character + mission, 10–10,000 chars. This is where the work goes.
`language`	—	2-letter code (`en`, `it`, `fr`, …). Default `en`. Drives transcription + the voice list.
`voice_config`	—	The voice to speak with. Pick one from `list_voices`.
`model_config`	—	The LLM behind the conversation. Defaults to Agoralia's recommended model.
`first_message`	—	What the agent says first. Omit to let it open naturally.
`max_duration_seconds`	—	Hard cap per call, 10–43200. Default `600` (10 min).
`recording_enabled`	—	`null` keeps the default (recording on, unless a country forbids it). `false` records no audio (transcript + structured data still produced). You cannot force it on where a jurisdiction forbids recording.

Other optional fields exist (transcriber_config, end_call_message, voicemail_message, analysis_config, compliance_config, hooks, metadata, …) — all default to empty.

1. Create

One core, three front doors

Every step shows the REST call and the MCP tool. The CLI wraps the same endpoints. Use whichever fits your workflow.

REST

curl -X POST https://api.agoralia.app/api/v1/agents \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound — Support EN",
    "language": "en",
    "system_prompt": "You are a friendly support agent for Acme. Answer questions, stay concise, and offer to book a callback if you cannot resolve the issue.",
    "voice_config": { "provider": "vapi", "voiceId": "..." }
  }'

MCP

create_agent(
  name="Inbound — Support EN",
  language="en",
  system_prompt="You are a friendly support agent for Acme...",
  voice_config={ "voiceId": "..." }
)

The response returns the created agent (with its id). It is not yet callable.

2. Configure

Pick a voice with list_voices, then refine the agent with PATCH /agents/{id} (MCP update_agent). Updates are partial — send only the fields you change.

REST

curl -X PATCH https://api.agoralia.app/api/v1/agents/AGENT_ID \
  -H "X-API-Key: ag_..." \
  -H "Content-Type: application/json" \
  -d '{ "first_message": "Hi, this is Acme support — how can I help?", "max_duration_seconds": 480 }'

Setting recording_enabled returns a recording_advisory in the response that explains the consequence. See Compliance for the per-country rules.

3. Publish

Sync the agent to the voice provider so it can place calls. This creates the provider assistant on first publish and updates it on later publishes.

REST

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

MCP

publish_agent(agent_id="AGENT_ID")

Response

{ "agent_id": "AGENT_ID", "provider_agent_id": "...", "published": true }

Publish errors are actionable

422 means the agent's config is incomplete (e.g. no voice configured) or the agent is inactive — the message tells you what to fix. 502 is a transient provider error; retry.

Test before you dial real numbers

Use test_agent (MCP) to dry-run the agent's behaviour, or place a single call to your own phone — see Single call.

Phone numbers — assign a number to call from.
Knowledge base — give the agent facts to draw on.
Single call · Campaigns

Agents

Agents

The agent model

1. Create

2. Configure

3. Publish

Test before you dial real numbers

Next

On this page