#An AI agent in your iOS app

To put an AI agent inside your iPhone app, add Vatio's Swift package, create a publishable key that allows your app's bundle id, and bind a VatioChat to your own SwiftUI views. 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 iOS 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 package, the tokens and a SwiftUI 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. For Android, see the Android 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 "which classes am I booked into?" from that member'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 Swift package for iOS 15 or later, with no dependencies beyond Foundation and Combine, and no UI.

#Allow your app and add the package

Create a publishable key for the app's bundle id (ios-app:// plus the bundle id) and add the Swift package https://github.com/vatio-ai/ios in Xcode. The exact commands, the Package.swift form and the rule that a vat_ developer token never ships in an app are in Setup:

vatio keys create publishable --env live --label ios --origin ios-app://example.northpoint.app

A key that does not allow your bundle id fails with origin_not_allowed. 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

import SwiftUI
import Vatio

struct AssistantView: View {
    @ObservedObject var chat: VatioChat
    @State private var text = ""

    var body: some View {
        VStack {
            ScrollView {
                LazyVStack(spacing: 12) {
                    ForEach(chat.messages) { message in
                        Text(LocalizedStringKey(message.content))   // basic Markdown
                            .frame(maxWidth: .infinity,
                                   alignment: message.isFromVisitor ? .trailing : .leading)
                            .opacity(message.isPending ? 0.6 : 1)
                    }
                    if chat.isTyping { ProgressView() }
                }
                .padding()
            }
            HStack {
                TextField("Ask anything", text: $text)
                Button("Send", action: send)
            }
            .padding()
        }
        .task { await chat.resume() }
    }

    private func send() {
        let question = text
        text = ""
        Task {
            do { try await chat.send(question) }
            catch { text = question }   // send removed the pending message
        }
    }
}

Create the chat once, for example as a @StateObject holding VatioChat(Vatio(workspace: "northpoint-fitness", token: "vatpub_...")). Creating it 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 VatioError with a code; failures outside a send land in chat.lastError.

#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 app binary 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: "northpoint-fitness", expiresIn: "1h" }
);

sub becomes $auth.subject, aud must be the workspace slug exactly, and exp is re-checked on every tool call. Add a metadata claim with a profile link and badges and the inbox shows them in the conversation header, so whoever reads it knows which member it is.

VatioChat takes the token when it is created, so signing in or out means a new one. A small store, like the one in the SDK's example app, does it:

@MainActor
final class AssistantStore: ObservableObject {
    @Published private(set) var chat: VatioChat
    private let vatio: Vatio

    init(vatio: Vatio) {
        self.vatio = vatio
        chat = VatioChat(vatio)
    }

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

    func 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_bookings.yml:

description: The signed-in member's upcoming class bookings.
when_to_use: A signed-in member asks about their own bookings or classes.
access: private
request:
  method: GET
  base_url: "$env.NORTHPOINT_API"
  path: /me/bookings
  headers:
    Authorization: "Bearer $auth.token"
respond:
  data:
    bookings: "$.bookings"
  message:
    when_empty: This member has no upcoming bookings.
    default: "Found {{count}} upcoming bookings."

Your endpoint verifies the JWT with the same public key and scopes the query to its sub. The tool takes no member id, and it cannot: a private tool that declares member_id, user_id, customer_id, account_id, patient_id or subject fails the deploy, because the model fills parameters and can be talked into filling in someone else's. book_class is private too, and takes only the class id.

workspace: northpoint-fitness
agent:
  name: Northpoint
  instructions: |
    You help members of Northpoint Fitness with classes, schedules and
    their own bookings.

    Schedules: call class_schedule.
    A member's own bookings: call my_bookings, and book_class to book.
    If you cannot see their bookings because they are not signed in,
    ask them to sign in to the app first. Never guess a booking.
  tools: [class_schedule, my_bookings, book_class, remember, recall]
auth:
  public_key: identity.pub

class_schedule is public, so it also answers someone who has not signed in, 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 view 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). Memory belongs to the contact: with remember and recall enabled, the agent sees the notes kept about a signed-in user, so a new conversation can start from what earlier ones established.

#Photos and voice notes

send(_: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. Recording needs NSMicrophoneUsageDescription in your Info.plist.

#Test against preview

The key decides which environment the app talks to, so a development build should not carry the live one. Create one for preview:

vatio push
vatio keys create publishable --env preview --label ios-dev --origin ios-app://example.northpoint.app

vatio env shows preview's details. Pick the key per build configuration:

#if DEBUG
let vatio = Vatio(workspace: "northpoint-fitness", token: "vatpub_PREVIEW_TOKEN")
#else
let vatio = Vatio(workspace: "northpoint-fitness", token: "vatpub_LIVE_TOKEN")
#endif

vatio chat speaks as you, the developer, not as a member, so test private tools from the app itself. Sign in on the simulator, ask about your bookings, 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 for another member's bookings: 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 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. The web version of this setup is An AI chat for your web app or site.

#Frequently asked questions

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

Add the Swift package at https://github.com/vatio-ai/ios, create a publishable key whose allowed origin is ios-app:// plus your bundle id, and create a VatioChat with it. The SDK keeps the conversation as observable state, so a SwiftUI view that observes it 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 iOS 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.

#Does the Vatio iOS SDK include a chat UI?

No. It is a Swift package with no UI and no dependencies: it gives you messages, typing, connection status, files and the feedback moment as state, and you draw the screens. The package README has a complete SwiftUI example, the repository includes a runnable example app, and Vatio Chat (github.com/vatio-ai/vatio-chat-ios) is a whole ChatGPT-style app built on it.

#Does the iOS 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 Android app: The same agent inside your Android app with the Kotlin SDK and a Compose screen.
• 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.