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

# Agents

> Create an agent, give it instructions and documents, and get replies from your backend.

An agent answers in Yoruba, Pidgin, Hausa, Igbo or Nigerian English. You set its instructions and tools in the dashboard or through the API, then send it messages.

## Get a reply

Only live agents answer. Turn an agent live in the dashboard, or with `PATCH /v1/agents/{agent_id}` and `{"status": "live"}`.

```bash theme={null}
curl https://api.vocalistic.ai/v1/agents/YOUR_AGENT_ID/responses \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: a-unique-value' \
  -d '{"input": "Wetin be una opening time?"}'
```

The reply comes straight back:

```json theme={null}
{
  "conversation_id": "conv_abc",
  "status": "open",
  "reply": "We dey open by 9am.",
  "speech_text": "We dey open by nine am.",
  "unverified_numbers": [],
  "tool_calls": [{"name": "knowledge_search", "input": {"query": "opening time"}, "output": {"results": []}}],
  "sources": ["opening-hours.md"],
  "usage": {"credits": 0.2, "quantity": 1, "unit": "reply"},
  "request_id": "req_abc"
}
```

Send `conversation_id` with the next message to continue the conversation. To hear the reply, pass `speech_text` to [`POST /v1/audio/speech`](https://docs.vocalistic.ai/speech), which is charged separately. `reply` keeps numbers as digits for reading, and `speech_text` has them as words.

`unverified_numbers` lists any number that isn't in the agent's instructions, documents, tool results or the conversation. It should be empty. If it isn't, check that reply before relying on it.

Sending the same `Idempotency-Key` with an API key returns the same reply, with no second charge. Keys last a day, and belong to one API key and one agent. Client tokens can't use them.

`tool_calls` shows each tool's input and output to API keys. Client tokens get tool names only, so a browser can't read your documents or what your webhook returned.

## Errors

| Code | Status | Meaning |
| - | - | - |
| `not_found` | `404` | No such agent or conversation, or the conversation has expired. |
| `agent_not_live` | `409` | The agent is a draft. |
| `request_in_progress` | `409` | This `Idempotency-Key` is still being used. |
| `idempotency_conflict` | `422` | This `Idempotency-Key` was used with a different request. |
| `conversation_busy` | `409` | A reply is still running in this conversation. |
| `conversation_ended` | `409` | The agent ended this conversation. Start a new one. |
| `insufficient_credits` | `402` | Top up to continue. |
| `rate_limited`, `too_many_concurrent_requests` | `429` | Wait, then try again. |
| `model_unavailable` | `503` | Try again shortly. You aren't charged. |

## Conversations

We keep a conversation for 1 hour after its last message, or for your organization's retention period if that's longer, and delete it within a day of that. A conversation older than this returns `404`. Delete one sooner with `DELETE /v1/conversations/{conversation_id}`.

## Knowledge

Upload TXT, Markdown, CSV, JSON or HTML files of up to 2 MB, or add short notes, up to 20 per agent. With **Knowledge search** on, the agent looks up answers there and `sources` names the documents it used.

An agent can repeat anything in its documents to whoever it's talking to, so don't upload anything callers shouldn't hear.

## Tools

| Tool | What it does |
| - | - |
| Knowledge search | Searches this agent's documents. |
| Collect caller details | Saves the details you list on the conversation. |
| End conversation | Closes the conversation. |
| HTTP webhook | Calls your backend. |
| Transfer to human, Send SMS | Coming soon. |

### Webhooks

Your endpoint must be a public `https` URL. We wait 5 seconds in total, read at most 8 KB and don't follow redirects. An agent can make at most 8 tool calls in a reply. A live agent's webhook needs a signing secret. A `POST` carries this JSON, and a `GET` sends the same fields as query parameters:

```json theme={null}
{"tool": "check_order", "arguments": {"order": "7"}, "agent_id": "agt_abc", "conversation_id": "conv_abc"}
```

Create a signing secret in the dashboard, then check `X-Vocalistic-Signature` on each request. It's `sha256=` followed by the hex HMAC-SHA256 of `{X-Vocalistic-Timestamp}.{body}`, keyed with your secret. For a `GET`, use the path and query in place of the body. Reject old timestamps.

A failed reply can be retried after a webhook has already run. Use `X-Vocalistic-Delivery`, which is unique to each call, to spot repeats, and make actions safe to repeat where you can.

## Testing

Send `"test": true` with an API key to run a draft. It's charged like any reply, but webhooks aren't called: the agent is told the action was simulated. A test conversation can't continue as a real one. The dashboard's test console does this for you.


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