AI agent for your app

An app agent is a voice assistant inside your mobile app or website that does things for your customers, not only answers questions: show the rice available in Warri, add it to the cart, ask for a saved address, book a pickup at a time they choose, check their open orders and rides. It uses the tools you connect to Kerabie, asks your app to show screens, and hands over to your team with a summary when it cannot help.

It is the AI voice agent with three additions: it can act as the signed-in customer, it can ask your app to show screens, and it can hand over to your team.

What you need

• Calls and the AI voice agent turned on in Settings → Calls, and call minutes on your plan.
• Your tools connected: your own AI tools (plain HTTP endpoints, the simplest start) or an MCP server.
• Your app or site, with the agent button added (below).

Voice needs a development build; the chat does not

The agent works in two ways: typed in the chat and spoken. The chat agent needs no native code and runs everywhere, including Expo Go. The voice agent uses native WebRTC, so in React Native and Expo it needs a development build and does not run in Expo Go. This is the same requirement as calls.

In Expo Go use the chat agent (agent on the provider). Import the voice agent from react-native-kerabie-helpdesk/calls only in builds that include it, and hide its button in Expo Go.

If your app already has LiveKit or another calling library

Check package.json before you add anything for voice.

Kerabie's calls connect a customer to your support team or the AI agent. They do not replace calls between your own users, such as a customer and a rider.

Public and secure tools

Choose the route for every tool when you connect it. Kerabie suggests one from the tool's read-only hint and its name (cart, order, address, pickup, payment); you confirm or change it.

For a secure tool, Kerabie sends the customer's token to your server in the X-Kerabie-User-Token header. The token is:

• passed by your app when the agent starts (getUserToken),
• kept encrypted (AES-256-GCM) in Redis, only for the length of the call (2 hours at most), and deleted when the call ends,
• never shown to the AI, and never written to logs or transcripts.

Your server checks the token the way it checks any customer token and acts for that customer. Never trust a customer id in the tool's arguments. If nobody is signed in, secure tools are not offered, and the agent tells the customer to sign in.

Screens instead of reading lists

Voice is poor for lists and worse for addresses. The agent asks your app to show a screen and waits for the customer's answer.

The agent only uses the screens your app registers. Addresses are never taken by voice, because speech recognition gets them wrong. Anything that places an order, books something or costs money is confirmed on screen first, with every detail and the price.

Start it by voice

In a React Native development build the customer can wake the voice agent by saying its name: "Ted", "hi Ted", "hello Ted". It listens only while the app is open on screen, uses recognition that runs on the phone by default, and should be a setting the customer turns on. See Wake by saying its name. It is not available in Expo Go, on the website or in Flutter yet.

App actions

Some things happen on the device, not on your server: a cart kept in your app's state, or starting your own checkout. Register them as actions in the app. Each one becomes a tool the agent can call (named action_<name>), runs in your app, and returns a short result the agent says back.

<KerAbieAgentButton
  actions={{
    add_to_cart: {
      description: 'Adds an item to the cart in the app. Use it when the customer says to add something.',
      parameters: { type: 'object', properties: { itemId: { type: 'string' }, quantity: { type: 'number' } }, required: ['itemId'] },
      run: async ({ itemId, quantity = 1 }) => { cart.add(itemId, quantity); return `Added ${quantity} to the cart` },
    },
  }}
/>

• Describe when to use each action (10 characters or more) and give its inputs as JSON Schema.
• Validate in run (stock, price) and throw when it cannot be done: the agent then tells the customer.
• The agent calls confirm_action before an action that places an order or costs money.
• Use a server tool instead when the data lives on your server. Use an action when it lives in the app.
• Website: Kerabie.agent.configure({ actions: { ... } }). Flutter: actions: {'add_to_cart': KerabieAgentAction(...)}.

Support and handoff

The same agent handles customer care. It answers from your Knowledge Base first. When the customer asks for a person, is upset, or reports a problem it cannot fix (a late rider, a wrong charge), it calls handoff_to_support:

1. It looks up the order or ride first, if a tool can.
2. Kerabie opens (or continues) the customer's conversation with a summary: what they asked, what the agent found and did, and what is unresolved.
3. The conversation is flagged for your team like any AI handoff: your handoff team, notifications and queue apply.
4. The agent tells the customer whether someone is online. It never promises a call back or a time.

If your conversation limit is used up, the agent says so instead of promising a reply.

Add it to your app

React Native

import { KerAbieAgentButton } from 'react-native-kerabie-helpdesk/calls'

<KerAbieAgentButton
  name="Kerabie Agent"
  getUserToken={async () => auth.currentToken()}
  ui={{
    pick_saved_address: async ({ purpose }) => pickAddress(purpose),
    pick_schedule: async ({ purpose, earliest }) => pickDateTime(),
    open_screen: async ({ screen }) => { navigation.navigate(screen); return 'opened' },
  }}
/>

A list, a confirmation and an address box are built in. See the React Native SDK.

Website

The chat window uses the agent as soon as you call configure; start() begins a voice conversation.

<script>
  window.addEventListener('kerabie:ready', (e) => {
    const kerabie = e.detail
    kerabie.agent.configure({
      name: 'Kerabie Agent',
      getUserToken: () => localStorage.getItem('token'),
      ui: {
        pick_saved_address: async ({ purpose }) => openAddressPicker(purpose),
      },
    })
    document.querySelector('#talk').onclick = () => kerabie.agent.start()
  })
</script>

Build the tools well

The agent is only as good as its tools. Use this checklist, or ask a coding agent with the Kerabie MCP to run plan_agent_for_app.

Design

• One tool per thing a customer asks for (search_products, add_to_cart, list_saved_addresses, create_pickup, list_open_orders), named in plain words. The description says when to use it.
• Return short, plain text or small JSON: names, prices, statuses. No internal ids in sentences, no HTML.
• Paginate lists (10 to 20 results) and say how many more there are. The agent shows them with show_items.
• Return a clear answer for empty results ("No rice in Warri right now") and for failures, so the agent can say it.

Writes

• Mark every tool that changes something, or touches the customer's own data, secure.
• Make writes safe to repeat: accept an idempotency key, or return the existing order when the same request arrives twice.
• Return what was done with the details ("Pickup booked for Friday 3 pm at 12 Market Road"), so the agent can say it back.

Scheduling

• Accept times as ISO 8601 with a timezone, and store them in UTC.
• Reject times in the past and outside your hours, and return the nearest available slots so the agent can offer them.
• Let customers list and reschedule or cancel what they booked. For recurring pickups, take a clear rule ("every Friday") and return the next date.

Addresses

• A secure list_saved_addresses tool returns ids and short labels. The agent shows them with pick_saved_address.
• A tool that takes a new address accepts the typed text, validates it, and returns what it understood so the customer can confirm it.

Support

• Give the agent read tools for order and ride status, so the summary it hands over is complete.
• Write Knowledge Base articles for delivery times, fees and refunds, so it answers common questions without a person.

Speed

• Keep a tool under 3 seconds. Kerabie waits 10 seconds, then tells the customer it failed.
• Cache read-only results on your side too, and mark read-only tools with the MCP readOnlyHint annotation so Kerabie can cache them.

Plans and limits

• Voice is metered as AI call minutes on your plan, one started minute at a time. When they run out the agent stops answering.
• Every switched-on tool, public or secure, counts towards your plan's AI tool limit.
• Handoffs create conversations, which count towards your plan's conversation limit.

Test it

1. Connect your server and use Test on each tool, public and secure.
2. Sign in as a test customer in a development build and talk to the agent: search, add to cart, pick an address, book a pickup, and check an order.
3. Try the failures: signed out (secure tools should not be offered), a past time, no results, a cancelled confirmation, and asking for a person.