#An AI agent in your Android app

To put an AI agent inside your Android app, add Vatio's Kotlin library, create a publishable key that allows your app's application id, and collect a VatioChat in your own Compose screen. The agent is the same one that answers in your web widget, WhatsApp and Instagram. In the app it can also know who the user is: your backend signs a token, and the agent's private tools read that user's own data.

This guide is the task path; every method and option is in the Android SDK reference.

#Start from an agent

1. Fastest, from any chat. Add the remote MCP server https://vatio.ai/mcp as a connector in Claude, ChatGPT or Cursor, sign in with a Vatio account and ask for the agent. It is created in a preview to try; nothing reaches users until you publish (Vatio in Claude and ChatGPT).
2. To build the agent into your app's code. In the app's project run npx @vatio-ai/skills, then /vatio-init (in Cursor or Codex, ask it to use that skill), then ask your coding agent to add the library, the tokens and a chat screen in your app's style, and /vatio-improve daily. See Build an AI agent.

The steps below are what your coding agent adds, for you to review, using a pet-care app as the example. For iPhone, see the iOS guide; for Flutter, the Flutter guide.

#Why put the agent in the app

A user signed in to your app is a visitor whose identity you already know. On WhatsApp and Instagram, a contact has to sign in on your site before a private tool runs. In the app, the same agent can answer "when is Luna's next appointment?" from that owner's own records.

It is not a second agent. A workspace runs one agent, and the app is one more channel for it. Instructions, tools, knowledge and the inbox are shared, so a fix you publish reaches every channel at once.

#What the SDK gives you, and what you build

The SDK is a Kotlin library for Android 8.0 (API 26) or later. Its only dependencies are OkHttp and kotlinx.coroutines, it declares the INTERNET permission itself, and it has no UI.

#Allow your app and add the library

Create a publishable key for the app's package name (android-app:// plus the package name) and add the library from JitPack. The exact commands and Gradle snippets, and the rule that a vat_ developer token never ships in an app, are in Setup:

vatio keys create publishable --env live --label android --origin android-app://example.pawline.app

A key that does not allow your package name fails with origin_not_allowed. A debug build with an applicationIdSuffix has a different package name (example.pawline.app.debug), so it needs that origin too, usually on the preview key below. The origin keeps the key on your app; it says nothing about who the user is. That comes from your backend, below.

#A first conversation

Keep the chat in a ViewModel, so it survives rotation, and close it when the ViewModel goes away:

class AssistantViewModel(application: Application) : AndroidViewModel(application) {
    private val vatio = Vatio(application, workspace = "pawline", token = BuildConfig.VATIO_TOKEN)

    var chat by mutableStateOf(VatioChat(vatio))
        private set

    fun send(text: String, restore: (String) -> Unit) {
        viewModelScope.launch {
            try { chat.send(text) }
            catch (e: VatioException) { restore(text) }   // send removed the pending message
        }
    }

    override fun onCleared() = chat.close()
}

Then collect it in Compose:

@Composable
fun AssistantScreen(model: AssistantViewModel = viewModel()) {
    val chat = model.chat
    val messages by chat.messages.collectAsStateWithLifecycle()
    val typing by chat.isTyping.collectAsStateWithLifecycle()
    var text by remember { mutableStateOf("") }

    LaunchedEffect(chat) { chat.resume() }

    Column(Modifier.fillMaxSize()) {
        LazyColumn(
            Modifier.weight(1f).padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(12.dp),
        ) {
            items(messages) { message ->
                Text(
                    message.content,
                    Modifier.fillMaxWidth().alpha(if (message.isPending) 0.6f else 1f),
                    textAlign = if (message.isFromVisitor) TextAlign.End else TextAlign.Start,
                )
            }
            if (typing) item { CircularProgressIndicator() }
        }
        Row(Modifier.padding(16.dp)) {
            OutlinedTextField(text, { text = it }, Modifier.weight(1f), placeholder = { Text("Ask anything") })
            Button(onClick = { val question = text; text = ""; model.send(question) { text = it } }) {
                Text("Send")
            }
        }
    }
}

Creating a VatioChat opens nothing: the conversation starts on the first send, so a user who never writes never becomes a contact. resume() reopens the stored conversation if there is one and never starts a new one. send throws a VatioException with a code; failures outside a send land in chat.lastError. The example app in the repository is a complete version, with an ask bar on a home screen, a conversation tab, photos and voice notes. Vatio Chat goes further: a ChatGPT-style app with the conversation list, the feedback card and settings, each in a file of its own.

#Sign the user in with a token your backend signs

To tell the agent who the user is, your backend signs a JWT and the app passes it along. The private key never goes in the app: an APK can be unpacked, and with that key anyone could claim to be any of your users. Vatio holds only the public half, so it can check an identity but never mint one.

Run vatio auth --new-key once. identity.pub stays in the workspace, named by the auth: block in vatio.yml. identity.pem goes into your backend as a secret, not into vatio secrets and not into the app. Then add an endpoint behind your app's own login that signs a short-lived RS256 token:

// Your backend, e.g. POST /me/vatio-token, behind your existing login
import jwt from "jsonwebtoken";

const visitorToken = jwt.sign(
  { sub: String(user.id), name: user.name, email: user.email },
  process.env.VATIO_IDENTITY_PRIVATE_KEY,
  { algorithm: "RS256", audience: "pawline", expiresIn: "1h" }
);

sub becomes $auth.subject, aud must be the workspace slug exactly, and exp is re-checked on every tool call. With Supabase Auth, an Edge Function can read the session and sign it (Supabase apps).

VatioChat takes the token when it is created, so signing in or out means a new one. Add this to the ViewModel; the LaunchedEffect(chat) above resumes whichever chat is current:

// visitorToken: what your backend's /me/vatio-token returned
fun signedIn(visitorToken: String) {
    chat.close()
    chat = VatioChat(vatio, visitorToken = visitorToken)
}

fun signedOut() {
    chat.close()
    chat = VatioChat(vatio)
}

#Private tools now run for that user

With a verified token, tools marked access: private run, and they reach your API with the user's own token. tools/my_appointments.yml:

description: The signed-in owner's upcoming appointments, for each of their pets.
when_to_use: A signed-in owner asks about their own pets' appointments.
access: private
request:
  method: GET
  base_url: "$env.PAWLINE_API"
  path: /me/appointments
  headers:
    Authorization: "Bearer $auth.token"
respond:
  data:
    appointments: "$.appointments"
  message:
    when_empty: This owner has no upcoming appointments.
    default: "Found {{count}} upcoming appointments."

Your endpoint verifies the JWT with the same public key and scopes the query to its sub. The tool takes no owner id, and it cannot: a private tool that declares a parameter such as user_id, customer_id or account_id fails the deploy, because the model fills parameters and can be talked into filling in someone else's.

workspace: pawline
agent:
  name: Pawline
  instructions: |
    You help Pawline customers with their pets' care: services, opening
    hours and their own appointments.

    Services and hours: answer from knowledge_lookup.
    An owner's own appointments: call my_appointments.
    If you cannot see their appointments because they are not signed in,
    ask them to sign in to the app first. Never guess an appointment.
  tools: [my_appointments, knowledge_lookup]
  knowledge: [services]
auth:
  public_key: identity.pub

The knowledge answers someone who has not signed in too, in the app or on any other channel. Tools and Authentication cover tools and tokens in depth.

#Conversation continuity

The SDK stores the conversation per workspace and signed-in user; call resume() when the screen appears. An anonymous conversation carries over when the user signs in, a different sub gets its own conversation, and chat credentials last 12 hours (Delivery and storage).

#Photos and voice notes

send(text, attachments) takes up to four files, and a voice note is transcribed before the agent answers. The types, sizes and the isMediaLabel rule are in Files and voice notes. Reading a picked file with VatioUpload.fromUri must happen off the main thread, and recording needs the RECORD_AUDIO permission, asked for at runtime.

#Test against preview

The key decides which environment the app talks to, so a debug build should not carry the live one. Create one for preview, with the debug build's package name:

vatio push
vatio keys create publishable --env preview --label android-dev --origin android-app://example.pawline.app.debug

Pick the key per build type:

android {
    buildFeatures { buildConfig = true }
    buildTypes {
        debug {
            applicationIdSuffix = ".debug"
            buildConfigField("String", "VATIO_TOKEN", "\"vatpub_PREVIEW_TOKEN\"")
        }
        release {
            buildConfigField("String", "VATIO_TOKEN", "\"vatpub_LIVE_TOKEN\"")
        }
    }
}

vatio chat speaks as you, the developer, not as an owner, so test private tools from the app itself. Sign in on the emulator, ask about your appointments, and read the conversation back with vatio chat show CHAT_ID (chat.conversationId holds the id). It shows every tool call, what your backend answered and whether the token was accepted: a wrong key, an expired exp or a wrong aud leaves the user anonymous instead of failing. no_agent_deployed means nothing is deployed to the token's environment yet. Then ask about another owner's pet: with no id parameter there is nothing for the model to fill in, and your endpoint answers only for the token's sub.

#Limits

Message length, file limits, rate limits and reply style are the same as on the web: see SDK limits. On rate limiting the SDK throws rate_limited: back off rather than retry at once.

#What the SDK does not do

• No push notifications. Nothing in the SDK registers for them. Replies arrive while the app is connected, and when it comes back from the background the SDK reconnects and fetches what it missed.
• No voice calls. Voice notes, yes; a live voice conversation, no.
• No files from the agent. It reads images, audio and PDFs, but its replies are text: it cannot generate or send files or images.
• No first messages. The agent answers what the user sends; it never starts a conversation.

#Ship it

When the preview answers well, publishing is your decision: ask to publish (vatio publish), which goes through the checks. The Free plan includes the owner's own WhatsApp number or Instagram account if you want those channels too; see Pricing.

Ship the release build with the live key. Conversations from the app land in the same inbox as the web and any other channel, with every tool call. A supervisor can take one over or report a wrong reply with Report this reply, and each report becomes a test: /vatio-improve fixes the cause and tests it on preview, and you approve publication. See Improve.

#Frequently asked questions

#How do I add an AI chat agent to my Android app?

Add the library com.github.vatio-ai:android from JitPack, create a publishable key whose allowed origin is android-app:// plus your application id, and create a VatioChat with it. The SDK keeps the conversation as StateFlows, so a Compose screen that collects them redraws as replies arrive. If you build the app with Claude Code, Cursor or Codex, ask your coding agent to do each of these steps and write the chat screen.

#Is it safe to ship the Vatio token inside an Android app?

The publishable vatpub_ key is meant to ship in the app. It selects one workspace and environment and only works from its allowed origins, but it does not prove who the user is. Never put a vat_ developer token or your identity private key in an app.

#Can the agent read the signed-in user's own data in my app?

Yes. Your backend signs a short-lived RS256 JWT for the user, the app passes it to VatioChat as the visitor token, and tools marked access: private run for that user. Your endpoint verifies the same token and scopes the query to its sub. With Supabase Auth, an Edge Function signs it.

#Does the Vatio Android SDK include a chat UI?

No. It is a Kotlin library with no UI: it gives you messages, typing, connection status, files and the feedback moment as StateFlows, and you draw the screens in Compose or Views. The repository includes a runnable Compose example app.

#Does the Android SDK support push notifications or voice calls?

No. Replies arrive over a WebSocket while the app is connected, and the SDK fetches anything it missed when it reconnects. Users can send voice notes, which are transcribed before the agent answers, but there are no voice calls and the agent replies in text.

#Related guides

• An AI agent in your iOS app: The same agent inside your iPhone app with the iOS SDK.
• An AI chat for your web app or site: One script tag puts the agent in your web app or site.
• An AI agent on WhatsApp: Add WhatsApp to your app's agent.
• Build an AI agent for your app: The two-step entry and trying the preview before publishing.