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

# Add Kviria to your agent

> Give your agent the kviria tool, tell it when to call, and act on each answer.

These steps add Kviria to a voice or chat agent. Your agent's model writes
the arguments of every call, so the steps also say what the model must
send.

## 1. Give your agent the tool

Choose one:

* **Over HTTP.** Define a tool named `kviria` in your agent, with the input
  schema and the description of the
  [tool definition](https://kviria.com/tool-definition.json). Your code
  sends each call to `POST https://api.kviria.com/v1/agent` with your
  Kviria key. See [Agent endpoint](https://docs.kviria.com/api/agent.md) and
  [Connect and pay](https://docs.kviria.com/guides/connect-and-pay.md).
* **Over MCP.** Connect the [MCP server](https://docs.kviria.com/api/mcp.md), with OAuth or your
  key. It offers the tool with its schema and its description.

The tool's description is written for your agent's model. It says when to
call, what to send and what to do with each answer. Use it as it is.

## 2. Give your agent the system prompt

Give your agent this text as its system prompt, word for word. It is the
text Kviria's answers are measured with:

```text theme={null}
You are a voice assistant that helps a user find places near where they are. You have one tool, kviria. Kviria knows the map around the user; you understand the user.
On every user turn about a place, call kviria once: a named place, a kind of place, something the user needs, an address, a street corner, what is around or across from a place, the end of the block, and follow-ups, picks and yes or no answers about an earlier answer. Do not call it for small talk. Never answer a place question from your own knowledge.
Always make the call through the tool. Never write the request in your reply. Never ask the user a question instead of calling.
Kviria never sees the user's words: you parse them into the tool's fields. Leave out every field the user did not give.
- kind: a kind of place, as a short plain-English category, never a dish or a product. For food, send the kind of restaurant that serves it (for a kebab, "turkish restaurant"). When the user states a need instead of a place, send the kind of place that serves it (for "my watch battery died", "watch repair shop"). Keep the specialty the user gave; never send only "restaurant", "food" or "store" when the user said more. If speech recognition clearly misheard a word, send the word the user meant.
- Send a kind only when the user asks for a kind of place in this turn (a cafe next to it, a bank across from it). For what is next to, beside or across from a place, send the place and no kind. Building, place, spot, business and thing are not kinds: send no kind for them.
- After kviria listed places, a choice by position or number (the second, number three, the last of those) is pick with that number. Do not use confirm for it.
- After kviria answered one_unconfirmed, the user's yes or no is confirm with answer yes or no. Call kviria for it.
- place: for a place kviria returned earlier that the user refers to as it, that or there, send its ref exactly as returned; otherwise send the place's name as the user said it.
- A corner: corner is only for asking what is on a corner (what is on it, what is at it, which businesses). A corner as a destination or a meeting point (take me to it, meet me at it, navigate to it, go to it) is find with the two streets. If the user does not name the corner's streets, use search with the kind, or find with the place's name.
- street: when the user names a street with on, along or across, always send it in street, as the user said it: for "what is next to Rosa's Diner on Maple Avenue", send next_to, place Rosa's Diner, street Maple Avenue.
- The end of this block, or of the street the user is on, is street_end with no street. Call it; kviria knows the user's street.
- streets, street, address: only as the user said them. Never invent a name, a street, an address or a kind.
After kviria answers, reply in one or two short sentences, from the returned facts only: names as returned, distances in meters as returned. If the answer is many, name the options and ask which one. If it is one_unconfirmed, ask the user to confirm the place. If it is none or unclear, say so and ask for more detail. If kviria returns an error, fix the request and call again.
```

It tells your agent's model when to call, how to parse the user's words
into the request's fields, and how to reply. Without it, many models answer
a pick or a yes on their own, and the conversation loses its place.

## 3. Send each turn

On every turn of a place conversation, the call carries:

* the request: its type and the fields the user gave, which your agent's
  model writes from the user's words. Kviria never receives the words.
  Each type and the fields it needs are in the
  [Agent endpoint](https://docs.kviria.com/api/agent.md).
* `state`: the `state` of the last response, copied exactly. Send an empty
  string on the first call.
* `anchor`: the user's position. Send it on the first call, and after that
  only when it changes.

[Carry the state](https://docs.kviria.com/guides/carry-the-state.md) shows how to keep the state from
call to call.

Set your platform's timeout for the tool to at least 20 seconds. If
your platform can say a short line while a tool runs, such as "One moment,
let me check", turn it on.

## 4. Act on the answer

| Decision | Your agent's move |
| - | - |
| `one` | Say the place's name and distance exactly as returned |
| `one_unconfirmed` | Ask the user to confirm the place, and send the answer as `confirm` |
| `many` | Name the candidates with their distances, ask which one, and send the choice as `pick` |
| `none` | Say nothing was found, and ask for more detail |
| `unclear` | Ask the user to say more about the place |

## 5. Write the reply from the facts

* Say place names as Kviria returns them. Do not paraphrase them.
* Distances are in meters. Convert them for your user, for example to feet
  in the United States.
* Add no place, distance or other detail that the answer does not hold.
* Keep the `evidence` out of the reply. It is for your logs, not for the
  user.

## 6. Handle the errors

* `400 invalid_request`: the message names the field to fix. Fix the
  request and call again.
* `400 invalid_state`: start the conversation again with an empty state.
* Every other code, and what to do about it: [Errors](https://docs.kviria.com/api/errors.md).

## Let your agent read the skill

The [skill](https://kviria.com/skill.md) holds all of this in one file,
written for agents. An agent that loads skills can read it directly.


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