Agents API: create and manage voice agents

An agent is the reusable configuration a call runs: what it says first, how it behaves, which voice, which language, and when it must stop. Calls reference an agent by ID; per-call differences go in variables. An agent runs either one prompt (system_prompt) or a graph of steps (flow). See Node-based agents for the graph. Base URL https://sandbox.voice.miraiminds.co. All endpoints require Authorization: Bearer sk_live_….

Tools

Add tools to connect your APIs before, during, or after a call. On-call HTTP tools can run synchronously or in the background, with the result returned to the voice agent when ready. See Tools for setup, conditions, secrets, callbacks, and examples.

Knowledge bases

Add knowledge to let the agent answer callers from your website, files, text and FAQ pairs. It names up to five knowledge bases and how the agent uses them. See Knowledge bases for sources, modes and limits.

Node-based agents

Add flow to run the conversation as a graph: nodes with their own instructions, and transitions the model takes when their conditions are met. With a flow, system_prompt and first_message are optional and unused, and only pre_call and post_call tools are allowed. See Node-based agents for the schema and a worked example.

The agent object

{
  "id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
  "object": "agent",
  "name": "Order Confirmation",
  "system_prompt": "You are Priya from Acme. Confirm order {{order_id}} with {{customer_name}}…",
  "first_message": "नमस्ते {{customer_name}}, मैं Acme से Priya बोल रही हूँ।",
  "voice": { "voice_id": "ashu", "language": "hi-IN" },
  "language": "hi-IN",
  "max_duration_secs": 300,
  "end_call": {
    "enabled": true,
    "message": "धन्यवाद, आपका दिन शुभ हो।",
    "confirm": true
  },
  "voicemail": { "action": "hangup" },
  "background_sound": { "sound": "off" },
  "behavior": {
    "interruptions": "normal",
    "adaptive_interruptions": true,
    "pass_through": []
  },
  "created_at": "2026-07-26T09:14:02Z",
  "updated_at": "2026-07-26T09:14:02Z"
}

Fields

Field	Type	Required	Description
`name`	string	yes	Human label. Shown in logs and the console.
`system_prompt`	string	yes, unless `flow` is set	The agent’s instructions. Supports `{{variable}}` placeholders. Unused on a node-based agent.
`first_message`	string	yes, unless `flow` is set	Spoken the moment the callee answers, before the model runs. Keep it short, because it sets your first-audio latency. Unused on a node-based agent: its start node’s `greeting` opens the call.
`voice`	object	yes	See Voice.
`language`	string	yes	BCP-47 conversation language, e.g. `hi-IN`, `en-IN`. Drives ASR and the model’s default output language.
`secondary_languages`	array	no	Other languages callers may speak: up to 4 of `hi`, `en`, `gu`, `mr`, `bn`, `ta`, `te`, `kn`, `ml`, `pa` and `od`. Speech recognition listens for them as well as `language`. Always returned, `[]` when there are none.
`max_duration_secs`	integer	no	Hard cap. When it is reached, the call ends with `ended_reason: exceeded-max-duration`. Minimum `30`, maximum `1800`, default `300`.
`tools`	array	no	Tool definitions for this agent. See Tools. PATCH replaces the full list.
`analysis`	object	no	What to work out after each call: a summary, a success verdict, extracted fields and the follow-up message to send. See Analysis. PATCH replaces the whole object.
`emit_processed_webhook`	boolean	no	Defaults to `true`. Set `false` to suppress `call.processed` while keeping analysis and post-call tools enabled.
`end_call`	object	no	See Ending a call.
`voicemail`	object	no	See Voicemail.
`background_sound`	string \| object	no	Room ambience under the agent’s voice. See Background sound. Default `off`.
`behavior`	object	no	How the agent takes turns with the caller. See Behavior. Default `{"interruptions": "normal", "adaptive_interruptions": true, "pass_through": []}`.
`flow`	object \| null	no	A node graph. Makes this a node-based agent. Present on the agent object only when set. PATCH replaces the whole graph; `null` removes it.

Server-set and read-only: id, object, created_at, updated_at.

Analysis

analysis reads each finished call once more, after the hangup, so it never slows the conversation. Turn it on with "enabled": true and describe what you want in prompt, success_criteria and output_schema. Add templates and the agent also picks the message template to send next, such as a WhatsApp or SMS template, and fills in its variables from the conversation. See Call analysis for every field, the result and two worked examples.

{
  "analysis": {
    "enabled": true,
    "prompt": "Summarise the call in two sentences: what the customer wanted and what was agreed.",
    "success_criteria": "The customer confirmed the order or chose a payment method.",
    "templates": {
      "instructions": "Pick the WhatsApp message to send. Choose none if the customer declined.",
      "items": [
        {
          "name": "payment_link_hi",
          "language": "hi",
          "description": "Sends the payment link when the customer agreed to pay online.",
          "variables": [
            { "key": "1", "description": "Customer first name" },
            { "key": "2", "description": "Order amount in rupees, digits only" }
          ]
        }
      ]
    }
  }
}

Calls from

calls_from sets the number the agent’s outbound calls and campaigns ring from when they do not choose one. Send { "pool_id": "pool_…" } for a phone pool, or { "phone_number_id": "phn_…" } for one of your numbers, never both. null unsets it. See phone numbers and pools for the order a call’s number is chosen in.

Voice

{ "voice": { "voice_id": "ashu", "language": "hi-IN" } }

Field	Type	Description
`voice_id`	string	Required. A voice from the catalogue: `ashu`, `neha`, `shruti`, `sameer`, `munshi` or `tanvi`. The same voices are available on every tier. It can also be the `id` of one of your workspace’s custom voices (`cv_…`). Anything else returns a `400` that names the allowed set. See Voices.
`language`	string	Rendering language for that voice. Omit to inherit the agent’s `language`. Accepted and stored, not yet honoured. See the note below.

voice.language is recorded, not yet appliedThe field is validated, stored and echoed back, and it travels with the call payload. Today, though, the voice renders in the agent’s top-level language. If you set both to the same value, you get what you expect. If you set them differently, the top-level one wins until per-voice rendering ships.

Listen to the catalogue and pick a voice_id in the console. See Voices. One call can use a different voice and languages without changing the agent: send call_settings on the call, on a campaign contact, or from a pre-call tool.

Ending a call

The agent gets an end_call tool. When it fires, the agent speaks message and hangs up.

Field	Type	Default	Description
`enabled`	boolean	`true`	Set `false` to remove the tool entirely. The call then ends only when the callee hangs up or `max_duration_secs` is reached.
`message`	string	`""`	Spoken farewell, played after the agent’s own goodbye when the call ends. It is empty by default, so the agent’s last line is the farewell. Live today.
`confirm`	boolean	`true`	Require a second `end_call` within the confirmation window before hanging up. This stops fast models from ending the call on a bare “ok”.

If you define an explicit end_call entry in tools, that entry controls whether the tool is available, including its condition. Its builtin.enabled, builtin.message, and builtin.confirm settings override the corresponding agent settings when supplied. See Tools.

Leave confirm: true unless you are running a one-turn notification. It costs one extra turn in the rare case and prevents the far more expensive failure of hanging up on a customer mid-sentence.

Voicemail

{
  "voicemail": {
    "action": "message",
    "message": "Hi, this is Acme calling about your order. We'll try again later."
  }
}

Field	Type	Description
`action`	`hangup` \| `message`	What to do when an answering machine is detected. Default `hangup`.
`message`	string	Required when `action` is `message`. Spoken once, then the call ends.

Either way the call ends with status: voicemail and fires a call.voicemail event. Voicemail detection is available on every tier. See tiers.

Background sound

An agent speaking out of complete silence is the most obvious sign that nobody is there. background_sound plays room ambience under the voice for the whole call.

{ "background_sound": "office" }

Or, with the level:

{ "background_sound": { "sound": "office", "volume": 0.2 } }

Field	Type	Description
`sound`	`off` \| `office`	Which room. Default `off`.
`volume`	number	`0` to `1`, default `0.08`. The default sits about 22 dB under the agent’s voice, so you notice the room when the line goes quiet but it never competes with the words. Raise it if you want the room more present. A bed at `0.3` is already at conversation level.

Before you turn it on, note two things:

The bed is in the call recording too, because it is what the callee heard. If you run your own transcription over recordings, test it first.
It does not touch what the agent hears. Ambience is mixed into the outbound audio only, so your callers’ speech recognition is unchanged.

Behavior

behavior sets how the agent takes turns with the caller: when it answers, and what makes it stop talking. In the console it is Agent Studio → Behavior → Interruptions, with the Adaptive interruptions switch at the top.

{
  "behavior": {
    "adaptive_interruptions": true,
    "interruptions": "normal",
    "pass_through": []
  }
}

Field	Type	Description
`adaptive_interruptions`	boolean	Mirai’s turn-taking. Default `true`. See Adaptive interruptions.
`interruptions`	`easy` \| `normal` \| `firm` \| `never`	How much the caller has to say before the agent stops talking. Default `normal`. See Fixed rules.
`pass_through`	array of strings	Your own words that never interrupt the agent, on top of built-in ones such as “haan” and “ok”. Default `[]`. See Pass-through words.

Adaptive interruptions

With adaptive_interruptions on, the default for every agent, the agent uses Mirai’s turn-taking:

It knows when the caller has finished speaking, and answers then.
When the caller pauses in the middle of a thought, it waits and says a short “hmm” so they know it is still listening.
When the caller asks for a moment (“give me a minute”), it holds until they come back.
While it speaks, it ignores voices much quieter than the caller’s, such as someone else in the room. Those voices do not stop it, and their words are not passed to the agent.
If an interruption turns out to be nothing, it picks up the line it was cut off on.

Mirai’s turn-taking is available when the agent uses Mirai’s own LLM. An agent on another LLM provider follows the fixed rules, even with adaptive_interruptions on.

Fixed rules

Set adaptive_interruptions to false and the agent follows fixed rules. The interruptions preset sets how much the caller has to say to stop it, and pass-through words never stop it.

`interruptions`	The agent stops when the caller says
`easy`	One word, or about half a second of speech.
`normal`	Two words, or about 0.7 seconds of speech.
`firm`	Three words, or about 1.2 seconds of speech.
`never`	Nothing. The agent always finishes its line, then answers what the caller said.

A clear stop word such as “stop” or “ruko” interrupts at every setting except never. The preset and the pass-through words still apply while adaptive_interruptions is on. The console shows them only when the switch is off, and switching it on there sets interruptions back to normal. On a node-based agent, a node with allow_interrupt: false is never interrupted whatever this setting is, and never applies to every node.

Pass-through words

Callers often say a short word while the agent talks, to show they are listening. The built-in acknowledgements, “haan”, “ji”, “ok”, “hmm” and their equivalents, never interrupt at any setting. Add the words your own callers use with pass_through:

{ "behavior": { "pass_through": ["theek", "achha", "bilkul", "theek hai"] } }

A reply made only of acknowledgements and pass-through words, in any mix, does not stop the agent. Case and punctuation do not matter. With the list above, “Haan, theek hai.” passes through. “Theek hai, ek sawaal hai” is treated like any other speech, because “ek sawaal” is not on the list. The API saves each entry like this:

An entry is literal text, never a pattern.
Unicode is normalised (NFC), spaces at either end are trimmed, and runs of spaces inside collapse to one.
After that, each entry is 1 to 40 characters and at most 4 words.
Duplicates are removed ignoring case. The first spelling and the order are kept.
At most 30 entries remain.
null is saved as [].

For example, [" Theek ", "theek", "bilkul"] is saved as ["Theek", "bilkul"]. A list outside these limits is refused with 400 invalid_request, and the message names the field:

Message	Cause
`behavior.pass_through: entries must not be empty`	An entry is empty, only spaces, or `null`.
`behavior.pass_through: "<first 40 characters>…" is <length> characters, the maximum is 40`	An entry is longer than 40 characters.
`behavior.pass_through: "haan ji theek hai na" is 5 words, the maximum is 4`	An entry has more than 4 words.
`behavior.pass_through has 31 entries, the maximum is 30`	More than 30 entries remain after duplicates are removed.

A pass_through that is not an array, or an entry that is not a string, gets the JSON decoder’s message instead. A Realtime session started from the agent does not use pass_through yet.

Change behavior with PATCH

PATCH merges behavior field by field: the fields you send change and the others keep their values, unlike other nested objects, which are replaced whole. pass_through is a list, so the list you send replaces the saved one. To add a word, read the agent, add the word to behavior.pass_through and send the whole list. Send [] or null to clear the list, or "behavior": null to go back to the defaults. The change takes effect on the next call and is saved with each agent revision. This request moves an agent to the fixed rules, with a firmer preset and three words of its own:

cURL
Python
Node.js

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "behavior": {
      "adaptive_interruptions": false,
      "interruptions": "firm",
      "pass_through": ["theek", "achha", "bilkul"]
    }
  }'

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}

agent = httpx.patch(
    f"{API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    headers=auth,
    json={
        "behavior": {
            "adaptive_interruptions": False,
            "interruptions": "firm",
            "pass_through": ["theek", "achha", "bilkul"],
        }
    },
    timeout=30,
).raise_for_status().json()

print(agent["behavior"])

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };

const res = await fetch(`${API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ`, {
  method: "PATCH",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    behavior: {
      adaptive_interruptions: false,
      interruptions: "firm",
      pass_through: ["theek", "achha", "bilkul"],
    },
  }),
});
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
const agent = await res.json();

200 OK (excerpt)

{
  "id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
  "object": "agent",
  "behavior": {
    "interruptions": "firm",
    "adaptive_interruptions": false,
    "pass_through": ["theek", "achha", "bilkul"]
  }
}

To go back to turn-taking with the default preset, send { "behavior": { "adaptive_interruptions": true, "interruptions": "normal" } }. The pass-through words stay.

If your callers use a laptop’s built-in microphone in a busy room, keep adaptive_interruptions on and let the browser reduce noise. See Microphone capture.

Create an agent

POST /v2/agents

cURL
Python
Node.js

curl -X POST https://sandbox.voice.miraiminds.co/v2/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Confirmation",
    "system_prompt": "You are Priya from Acme. Confirm order {{order_id}} with {{customer_name}}.",
    "first_message": "नमस्ते {{customer_name}}, मैं Acme से Priya बोल रही हूँ।",
    "voice": { "voice_id": "ashu", "language": "hi-IN" },
    "language": "hi-IN",
    "max_duration_secs": 300,
    "end_call": { "enabled": true, "message": "धन्यवाद, आपका दिन शुभ हो।", "confirm": true },
    "voicemail": { "action": "hangup" }
  }'

import os, httpx

API = "https://sandbox.voice.miraiminds.co"
auth = {"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"}

agent = httpx.post(
    f"{API}/v2/agents",
    headers=auth,
    json={
        "name": "Order Confirmation",
        "system_prompt": "You are Priya from Acme. Confirm order {{order_id}} with {{customer_name}}.",
        "first_message": "नमस्ते {{customer_name}}, मैं Acme से Priya बोल रही हूँ।",
        "voice": {"voice_id": "ashu", "language": "hi-IN"},
        "language": "hi-IN",
        "max_duration_secs": 300,
        "end_call": {"enabled": True, "message": "धन्यवाद, आपका दिन शुभ हो।", "confirm": True},
        "voicemail": {"action": "hangup"},
    },
    timeout=30,
).raise_for_status().json()

print(agent["id"])

const API = "https://sandbox.voice.miraiminds.co";
const auth = { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` };

const res = await fetch(`${API}/v2/agents`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Order Confirmation",
    system_prompt: "You are Priya from Acme. Confirm order {{order_id}} with {{customer_name}}.",
    first_message: "नमस्ते {{customer_name}}, मैं Acme से Priya बोल रही हूँ।",
    voice: { voice_id: "ashu", language: "hi-IN" },
    language: "hi-IN",
    max_duration_secs: 300,
    end_call: { enabled: true, message: "धन्यवाद, आपका दिन शुभ हो।", confirm: true },
    voicemail: { action: "hangup" },
  }),
});
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
const agent = await res.json();

Responds with 201 Created and the full agent object.

Error	`error.code`	Cause
`400`	`invalid_request`	Missing required field, unknown `voice_id`, `max_duration_secs` out of range, a `behavior.pass_through` list outside its limits
`400`	`invalid_flow`	A problem in `flow`, or an `on_call` tool on a node-based agent. The body lists every problem with its path; see errors.
`401`	`unauthorized`	Bad or missing key

Get an agent

GET /v2/agents/{id}

cURL
Python
Node.js

curl https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

agent = httpx.get(
    f"{API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ", headers=auth, timeout=30
).raise_for_status().json()

const agent = await fetch(
  `${API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ`,
  { headers: auth }
).then((r) => r.json());

Responds with 200 OK and the agent object. You get 404 not_found if the agent was deleted, if the ID does not exist, or if it exists in another workspace. All three cases return the same response, so a 404 never hints that the ID is real. None of these cases returns 403; that status only means your key has been revoked. See errors.

List agents

GET /v2/agents?limit=&cursor=

curl "https://sandbox.voice.miraiminds.co/v2/agents?limit=20" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "data": [
    {
      "id": "agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
      "object": "agent",
      "name": "Order Confirmation",
      "system_prompt": "You are Priya from Acme. Confirm order {{order_id}} with {{customer_name}}…",
      "first_message": "नमस्ते {{customer_name}}, मैं Acme से Priya बोल रही हूँ।",
      "voice": { "voice_id": "ashu", "language": "hi-IN" },
      "language": "hi-IN",
      "max_duration_secs": 300,
      "end_call": {
        "enabled": true,
        "message": "धन्यवाद, आपका दिन शुभ हो।",
        "confirm": true
      },
      "voicemail": { "action": "hangup" },
      "background_sound": { "sound": "off" },
      "behavior": {
        "interruptions": "normal",
        "adaptive_interruptions": true,
        "pass_through": []
      },
      "created_at": "2026-07-26T09:14:02Z",
      "updated_at": "2026-07-26T09:14:02Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Each element is the full agent object, in the same shape GET /v2/agents/{id} returns, prompts included. There is no trimmed summary form, so a page of agents with long prompts makes a large response. Page through with limit instead of pulling everything at once. Deleted agents are excluded. See pagination.

Update an agent

PATCH /v2/agents/{id}

Send only the fields you are changing. Nested objects such as voice, end_call, voicemail, background_sound, analysis and tools are replaced wholesale, so to change end_call.message, send the whole end_call object. behavior is the one exception: it is merged field by field, though a pass_through list you send replaces the saved list. See Change behavior with PATCH. flow is replaced wholesale too: send the whole graph, or use PUT /v2/agents/{id}/flow. "flow": null turns a node-based agent back into a single-prompt agent.

cURL
Python
Node.js

curl -X PATCH https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_duration_secs": 180, "voice": { "voice_id": "neha", "language": "hi-IN" } }'

agent = httpx.patch(
    f"{API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ",
    headers=auth,
    json={"max_duration_secs": 180, "voice": {"voice_id": "neha", "language": "hi-IN"}},
    timeout=30,
).raise_for_status().json()

const agent = await fetch(
  `${API}/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ`,
  {
    method: "PATCH",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      max_duration_secs: 180,
      voice: { voice_id: "neha", language: "hi-IN" },
    }),
  }
).then((r) => r.json());

Responds with 200 OK and the updated agent object.

An update takes effect on the next call. Calls already queued, dialing or in_progress keep the configuration they were created with.

Delete an agent

DELETE /v2/agents/{id}

curl -X DELETE https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

204 No Content. The delete is soft: the agent stops appearing in GET /v2/agents and can no longer be used for new calls, but historical calls keep resolving their agent_id. Calls already in flight are not affected.

Read an agent’s logs

GET /v2/agents/{id}/logs?part=&level=&call_id=&name=&since=&until=&limit=&cursor=

Everything that happened on this agent’s calls, newest first. One row per event: a tool run, a tool the model asked for that the agent doesn’t have, the variables a call received, the post-call analysis, and each call starting and ending. It’s the same list the console shows in Agent Studio under Logs, so you can debug from code or from the console and see the same rows.

Query param	Description
`part`	Optional. One of `prompt`, `tools`, `variables`, `results`, `calls`. Leave it out for every part.
`level`	Optional. `error`, `warning` or `info`. `errors`, `warnings` and `all` also work.
`call_id`	Optional. Only this call’s rows.
`name`	Optional. Only rows about one tool, variable or result field. `calls` rows have no name, so a named query never returns them.
`since`, `until`	Optional. RFC 3339 bounds on the row time. `until` defaults to now and `since` to 7 days before `until`. They can be at most 90 days apart. Escape a `+` offset as `%2B`.
`limit`	Optional. 1–200, default 50.
`cursor`	Optional. The `next_cursor` from the previous page.

curl -G https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ/logs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --data-urlencode "level=error" \
  --data-urlencode "limit=20"

200 OK

{
  "data": [
    {
      "ts": "2026-10-15T09:41:07.412000Z",
      "call_id": "call_01JZR4M8T2K9P3Q7V5W1X6Y0AB",
      "part": "tools",
      "level": "error",
      "event": "tool_run",
      "name": "create_complaint",
      "summary": "create_complaint · transform failed · HTTP 200 · 1.2 s · function not defined: json/0",
      "detail": {
        "tool": "create_complaint",
        "phase": "on_call",
        "kind": "http",
        "status": "transform_failed",
        "error": "transform_failed",
        "http_status": 200,
        "ms": 1200,
        "attempt": 1
      }
    },
    {
      "ts": "2026-10-15T09:40:51.118000Z",
      "call_id": "call_01JZR4M8T2K9P3Q7V5W1X6Y0AB",
      "part": "prompt",
      "level": "warning",
      "event": "tool_missing",
      "name": "get_complaint_status",
      "summary": "get_complaint_status · not a tool on this agent · turn 4",
      "detail": {
        "name": "get_complaint_status",
        "turn": 4,
        "advertised": ["create_complaint"]
      }
    }
  ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMC0xNVQwOTo0MDo1MS4xMTgwMDBafjQ1"
}

Field	Type	Description
`ts`	string	When it happened, in UTC.
`call_id`	string	The call it happened on. Open it with `GET /v2/calls/{id}`.
`part`	string	The part of the agent it’s about: `prompt`, `tools`, `variables`, `results` or `calls`.
`level`	string	`error`, `warning` or `info`.
`event`	string	What happened. See the table below.
`name`	string	The tool, variable or result field it’s about. Empty on `calls` rows.
`summary`	string	One line that says what happened, so you rarely need `detail`.
`detail`	object	The full record. Its fields depend on `event`.

`part`	`event`	Levels
`tools`	`tool_run`	`info` when the tool ran, was skipped by its condition, is turned off, or the call ended while it ran. `error` for anything else: a timeout, an HTTP error, a failed transform.
`prompt`	`tool_missing`	`warning`. The model asked for a tool this agent doesn’t have. The call carried on without it. Usually the prompt names a tool you haven’t added.
`variables`	`received`	`info`. The variables a call started with, after defaults.
`results`	`analysis_done`, `analysis_failed`	`info` when the analysis finished. `warning` when it finished but took more than 10 seconds to arrive. `error` when it failed.
`calls`	`created`, `ended`	`ended` is `info` for a normal ending, `warning` when the caller never spoke, and `error` when the call failed for a technical reason.

Page with next_cursor until has_more is false. See pagination. A variables row’s detail holds the values the call received, such as a customer’s name or order number. Treat logs like the call data they come from, and keep your API key on your server.

Rows about variables and results start from calls made on 14 October 2026. Rows about tools the model asked for but the agent doesn’t have start from 15 October 2026.

Count errors and warnings

GET /v2/agents/{id}/logs/summary?since=&until=

How many errors and warnings each part had. Without since it counts the last 24 hours. These are the counts on Agent Studio’s section labels.

curl https://sandbox.voice.miraiminds.co/v2/agents/agt_01JZQ8F3K7M2N5P9R4T6V8W0XZ/logs/summary \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

200 OK

{
  "since": "2026-10-14T09:45:00.000000Z",
  "until": "2026-10-15T09:45:00.000000Z",
  "parts": {
    "prompt":    { "errors": 0, "warnings": 3 },
    "tools":     { "errors": 7, "warnings": 0 },
    "variables": { "errors": 0, "warnings": 0 },
    "results":   { "errors": 0, "warnings": 1 },
    "calls":     { "errors": 1, "warnings": 2 }
  }
}

Every part is always present, even when both counts are zero.

Status	Code	When
`400`	`invalid_request`	A query param is out of range: an unknown `part` or `level`, a `limit` outside 1–200, a bad timestamp, `since` not before `until`, a window over 90 days, or a cursor from somewhere else.
`404`	`not_found`	No agent with this ID in your workspace.
`500`	`internal`	We couldn’t read the logs just now. Try again. Don’t read it as an empty log.

Writing a good prompt

A single-prompt agent does one job, start to finish, usually in under two or three minutes. The prompting guide covers this in detail. In short:

Name the job in the first line. “Confirm order {{order_id}}. Nothing else.”
Cap reply length explicitly. “One or two short sentences.” Long turns are the single biggest driver of perceived latency.
State the ending condition. “When the customer confirms or refuses, thank them and call end_call.” Without this the model keeps talking.
Put per-call data in variables, not the prompt. One agent can then run thousands of calls without being re-created.
Write in the language you will speak. A Hindi call driven by an English prompt code-switches badly. Write the Hindi lines in Devanagari.

Prompts that cause trouble: multi-branch scripts (“if they say X, then go through the following seven questions”), which belong in a node-based agent; instructions that assume the model remembers a previous call; and data the agent must fetch mid-call, which is a job for an on-call tool.

Start here

Build

Prompting

Speech API

Text to speech

Speech to text

Language model

Money

Reference

Agents API: create and manage voice agents

Tools

Knowledge bases

Node-based agents

The agent object

Fields

Analysis

Calls from

Voice

Ending a call

Voicemail

Background sound

Behavior

Adaptive interruptions

Fixed rules

Pass-through words

Change behavior with PATCH

Create an agent

Get an agent

List agents

Update an agent

Delete an agent

Read an agent’s logs

Count errors and warnings

Writing a good prompt

​Tools

​Knowledge bases

​Node-based agents

​The agent object

​Fields

​Analysis

​Calls from

​Voice

​Ending a call

​Voicemail

​Background sound

​Behavior

​Adaptive interruptions

​Fixed rules

​Pass-through words

​Change behavior with PATCH

​Create an agent

​Get an agent

​List agents

​Update an agent

​Delete an agent

​Read an agent’s logs

​Count errors and warnings

​Writing a good prompt

Tools

Knowledge bases

Node-based agents

The agent object

Fields

Analysis

Calls from

Voice

Ending a call

Voicemail

Background sound

Behavior

Adaptive interruptions

Fixed rules

Pass-through words

Change behavior with PATCH

Create an agent

Get an agent

List agents

Update an agent

Delete an agent

Read an agent’s logs

Count errors and warnings

Writing a good prompt