Skip to main content
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. Your code sends each call to POST https://api.kviria.com/v1/agent with your Kviria key. See Agent endpoint and Connect and pay.
  • Over MCP. Connect the MCP server, 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:
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.
  • 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 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

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.

Let your agent read the skill

The skill holds all of this in one file, written for agents. An agent that loads skills can read it directly.