Multi-turn Conversations

Build conversational AI that maintains context across multiple messages.

iOSAndroid

Overview

On-device models are stateless, they don't remember previous calls. You hold the conversation history in an array and pass the full history on every request. The model uses it to produce context-aware responses.

Messages, the running history you pass to the AI
System prompt, instructions that define behavior
Context, the model sees every message you send

How It Works

Maintain an array of messages, append each turn, and pass it to sendMessage() (or streamMessage()).

import { sendMessage, type LLMMessage } from 'expo-ai-kit';

const messages: LLMMessage[] = [];

// First turn
messages.push({ role: 'user', content: 'My name is Alex.' });
const r1 = await sendMessage(messages);
messages.push({ role: 'assistant', content: r1.text });
// AI: "Nice to meet you, Alex!"

// Second turn, the AI has context from the array
messages.push({ role: 'user', content: 'What is my name?' });
const r2 = await sendMessage(messages);
messages.push({ role: 'assistant', content: r2.text });
// AI: "Your name is Alex."

You own the history: append the user message before each call and the assistant's reply after it. The library adds no hidden state.

System Prompts

A system prompt defines the AI's behavior and persona. Provide it two ways:

Option 1, the systemPrompt option

const response = await sendMessage(
  [{ role: 'user', content: 'Tell me a joke' }],
  { systemPrompt: 'You are a comedian who specializes in dad jokes.' }
);

Option 2, a system message in the array

const response = await sendMessage([
  { role: 'system', content: 'You are a comedian who specializes in dad jokes.' },
  { role: 'user', content: 'Tell me a joke' },
]);

If a system message is present in the array, the systemPrompt option is ignored.

Conversation Hook

A reusable React hook for managing a multi-turn conversation:

import { useState, useCallback } from 'react';
import { sendMessage, type LLMMessage } from 'expo-ai-kit';

export function useChat(systemPrompt?: string) {
  const [messages, setMessages] = useState<LLMMessage[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  const chat = useCallback(async (userMessage: string) => {
    setIsLoading(true);
    try {
      const next: LLMMessage[] = [
        ...messages,
        { role: 'user', content: userMessage },
      ];
      const response = await sendMessage(next, { systemPrompt });
      setMessages([...next, { role: 'assistant', content: response.text }]);
      return response.text;
    } finally {
      setIsLoading(false);
    }
  }, [messages, systemPrompt]);

  const clearChat = useCallback(() => setMessages([]), []);

  return { messages, isLoading, chat, clearChat };
}

Best Practices

1. Trim long conversations

As history grows, drop the oldest turns to stay responsive and within the model's context window.

const MAX_MESSAGES = 20;

function trim(messages: LLMMessage[]): LLMMessage[] {
  return messages.length <= MAX_MESSAGES ? messages : messages.slice(-MAX_MESSAGES);
}

const response = await sendMessage(trim(messages), { systemPrompt });

2. Send messages sequentially

Only one generation runs at a time, a concurrent call rejects with INFERENCE_BUSY. Wait for each response before sending the next.

// ❌ Bad, concurrent calls reject with INFERENCE_BUSY
await Promise.all([
  sendMessage([{ role: 'user', content: 'Question 1' }]),
  sendMessage([{ role: 'user', content: 'Question 2' }]),
]);

// ✅ Good, await each in turn
const r1 = await sendMessage([{ role: 'user', content: 'Question 1' }]);

3. Always include the full history

For context-aware replies, pass the complete conversation, not just the latest message.

// ❌ Loses context
await sendMessage([{ role: 'user', content: 'What did I just say?' }]);

// ✅ Includes history
await sendMessage([
  { role: 'user', content: 'My name is Alice.' },
  { role: 'assistant', content: 'Nice to meet you, Alice!' },
  { role: 'user', content: 'What is my name?' },
]);