Build an AI Assistant with Flutter

import 'package:stream_chat_flutter/stream_chat_flutter.dart'
    hide
        StreamingMessageView,
        AITypingIndicatorView,
        TypewriterState,
        TypewriterController,
        StreamTypewriterBuilder;
import 'package:stream_chat_flutter_ai/stream_chat_flutter_ai.dart';

import 'package:flutter/material.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart';

import 'src/home_page.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Use the same Stream app as the backend. The token must be signed with
  // that app's secret.
  final client = StreamChatClient('YOUR_STREAM_API_KEY');
  await client.connectUser(
    User(id: 'anakin_skywalker'),
    'USER_TOKEN', // demo only, see the notes below
  );

  runApp(MyApp(client: client));
}

class MyApp extends StatefulWidget {
  const MyApp({super.key, required this.client});

  final StreamChatClient client;

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  // The assistant can change this through the `setThemeMode` client tool.
  var _themeMode = ThemeMode.light;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Stream Chat AI Assistant',
      theme: ThemeData.light(),
      darkTheme: ThemeData.dark(),
      themeMode: _themeMode,
      builder: (context, child) => StreamChat(client: widget.client, child: child),
      home: HomePage(
        client: widget.client,
        onThemeModeChanged: (mode) => setState(() => _themeMode = mode),
      ),
    );
  }
}

// lib/src/agent_service.dart
import 'package:dio/dio.dart';
import 'package:flutter/foundation.dart';

class AgentService {
  /// Where the backend runs. The Android emulator reaches your machine at
  /// 10.0.2.2, because `localhost` there is the emulator itself.
  ///
  /// On a physical device, run `adb reverse tcp:3000 tcp:3000` and pass
  /// `--dart-define=AGENT_BASE_URL=http://localhost:3000`.
  static final baseUrl = switch (const String.fromEnvironment('AGENT_BASE_URL')) {
    '' when !kIsWeb && defaultTargetPlatform == TargetPlatform.android => 'http://10.0.2.2:3000',
    '' => 'http://localhost:3000',
    final url => url,
  };

  final _dio = Dio(
    BaseOptions(
      baseUrl: baseUrl,
      // Dio waits forever by default. `/start-ai-agent` makes several Stream
      // API calls of its own, hence the roomier receive timeout.
      connectTimeout: const Duration(seconds: 10),
      receiveTimeout: const Duration(seconds: 30),
    ),
  );

  /// Starts the AI agent in [channelId], which then answers every new message.
  Future<void> startAgent(String channelId, {String? platform}) async {
    await _dio.post<void>('/start-ai-agent', data: {
      'channel_id': channelId,
      if (platform != null) 'platform': platform,
    });
  }

  /// Tells the backend which client-side tools this app can run.
  Future<void> registerTools(String channelId, List<Map<String, Object?>> tools) async {
    if (tools.isEmpty) return;
    await _dio.post<void>('/register-tools', data: {'channel_id': channelId, 'tools': tools});
  }

  /// Asks the backend to boil [text] down to a short conversation title.
  Future<String?> summarize(String text, {String? platform}) async {
    final response = await _dio.post<Map<String, Object?>>('/summarize', data: {
      'text': text,
      if (platform != null) 'platform': platform,
    });
    return response.data?['summary'] as String?;
  }
}

// lib/src/typing_state_handler.dart
import 'dart:async';

import 'package:flutter/foundation.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart';

class TypingStateHandler extends ValueNotifier<AITypingState> {
  TypingStateHandler({required Channel channel}) : super(AITypingState.idle) {
    _subscription = channel.on().listen(_onEvent);
  }

  late final StreamSubscription<Event> _subscription;

  void _onEvent(Event event) {
    final state = switch (event.type) {
      // On failure the backend sends `ai_indicator.update` with
      // `AI_STATE_ERROR`, not a clear or stop, so `error` also ends a reply.
      EventType.aiIndicatorUpdate => event.aiState,
      EventType.aiIndicatorClear || EventType.aiIndicatorStop => AITypingState.idle,
      _ => null,
    };
    if (state != null) value = state;
  }

  @override
  void dispose() {
    unawaited(_subscription.cancel());
    super.dispose();
  }
}

// lib/src/conversation_view.dart
import 'package:flutter/material.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart'
    hide
        StreamingMessageView,
        AITypingIndicatorView,
        TypewriterState,
        TypewriterController,
        StreamTypewriterBuilder;
import 'package:stream_chat_flutter_ai/stream_chat_flutter_ai.dart';

import 'ai_message_item.dart';
import 'typing_state_handler.dart';

class ConversationView extends StatefulWidget {
  const ConversationView({
    super.key,
    required this.channel,
    this.onGeneratingChanged,
  });

  final Channel channel;

  /// Called when the assistant starts or stops replying, so the composer can
  /// swap its send button for a stop button.
  final ValueChanged<bool>? onGeneratingChanged;

  @override
  State<ConversationView> createState() => _ConversationViewState();
}

class _ConversationViewState extends State<ConversationView> {
  late final _typingStateHandler = TypingStateHandler(channel: widget.channel)
    ..addListener(_reportGenerating);
  var _typewriterState = TypewriterState.idle;

  @override
  void dispose() {
    _typingStateHandler.dispose();
    super.dispose();
  }

  void _reportGenerating() {
    widget.onGeneratingChanged?.call(switch (_typingStateHandler.value) {
      AITypingState.thinking || AITypingState.checkingSources || AITypingState.generating => true,
      _ => false,
    });
  }

  void _onTypewriterStateChanged(TypewriterState state) {
    if (state == _typewriterState) return;
    // Reported while the message list builds, so wait for the frame to end.
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted) return;
      setState(() => _typewriterState = state);
    });
  }

  @override
  Widget build(BuildContext context) {
    return StreamChannel(
      channel: widget.channel,
      child: Column(
        children: [
          Expanded(
            child: StreamMessageListView(
              messageBuilder: (context, message, defaultProps) {
                if (message.isAI) {
                  return AIMessageItem(
                    message: message,
                    onTypewriterStateChanged: _onTypewriterStateChanged,
                  );
                }
                return DefaultStreamMessageItem(props: defaultProps);
              },
            ),
          ),
          ValueListenableBuilder(
            valueListenable: _typingStateHandler,
            builder: (context, aiTypingState, _) => AITypingIndicatorStateView(
              typewriterState: _typewriterState,
              aiTypingState: aiTypingState,
            ),
          ),
        ],
      ),
    );
  }
}

extension on Message {
  /// Whether the AI assistant wrote this message.
  bool get isAI => extraData['ai_generated'] == true;
}

// lib/src/ai_message_item.dart
import 'package:flutter/material.dart';
import 'package:flutter_math_fork/flutter_math.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart'
    hide StreamingMessageView, TypewriterState;
import 'package:stream_chat_flutter_ai/stream_chat_flutter_ai.dart';
import 'package:url_launcher/url_launcher.dart';

import 'code_highlighter.dart';

class AIMessageItem extends StatelessWidget {
  const AIMessageItem({super.key, required this.message, this.onTypewriterStateChanged});

  final Message message;
  final ValueChanged<TypewriterState>? onTypewriterStateChanged;

  @override
  Widget build(BuildContext context) {
    // Use the same text style as the regular message bubbles.
    final bodyStyle = context.streamTextTheme.bodyDefault.copyWith(
      color: context.streamColorScheme.textPrimary,
    );

    return Padding(
      padding: const EdgeInsets.all(16),
      child: StreamingMessageView(
        text: message.text ?? '',
        onTypewriterStateChanged: onTypewriterStateChanged,
        styleSheet: MarkdownStyleSheet.fromTheme(Theme.of(context)).copyWith(p: bodyStyle),
        codeHighlighter: highlightCode,
        mathBuilder: _buildMath,
        // Models write `$…$` more often than the default `\(…\)` / `\[…\]`.
        useDollarDelimitersForMath: true,
        onTapLink: (text, href, title) => _openLink(href),
      ),
    );
  }

  static Widget _buildMath(
    BuildContext context,
    String tex,
    TextStyle? style, {
    required bool inline,
  }) {
    return Math.tex(
      tex,
      textStyle: style,
      mathStyle: inline ? MathStyle.text : MathStyle.display,
      // Models emit malformed TeX often enough; show the source instead.
      onErrorFallback: (error) => Text(tex, style: style),
    );
  }

  static Future<void> _openLink(String? href) async {
    final uri = href == null ? null : Uri.tryParse(href);
    if (uri == null) return;
    try {
      if (await launchUrl(uri, mode: LaunchMode.externalApplication)) return;
    } catch (e) {
      debugPrint('Failed to open link $href: $e');
      return;
    }
    debugPrint('Could not open link: $href');
  }
}

class AITypingIndicatorStateView extends StatelessWidget {
  const AITypingIndicatorStateView({
    super.key,
    required this.aiTypingState,
    required this.typewriterState,
  });

  final AITypingState aiTypingState;
  final TypewriterState typewriterState;

  @override
  Widget build(BuildContext context) {
    final colors = Theme.of(context).colorScheme;
    // `error` wins over a still-running typewriter: the reply won't finish.
    final indicatorText = switch ((typewriterState, aiTypingState)) {
      (_, AITypingState.error) => 'Something went wrong. Please try again.',
      (TypewriterState.typing, _) || (_, AITypingState.generating) => 'Generating',
      (_, AITypingState.thinking) => 'Thinking',
      (_, AITypingState.checkingSources) => 'Checking sources',
      _ => null,
    };
    final isError = aiTypingState == AITypingState.error;

    return AnimatedSwitcher(
      duration: const Duration(milliseconds: 300),
      child: switch (indicatorText) {
        final text? => Container(
          key: ValueKey(text),
          width: double.infinity,
          color: isError ? colors.errorContainer : colors.surfaceContainerHighest,
          padding: const EdgeInsets.all(8),
          child: isError
              ? Text(text, style: TextStyle(color: colors.onErrorContainer, fontSize: 16))
              : AITypingIndicatorView(
                  text: text,
                  textStyle: TextStyle(color: colors.onSurface, fontSize: 16),
                ),
        ),
        null => const SizedBox.shrink(),
      },
    );
  }
}

// lib/src/home_page.dart
import 'dart:async';

import 'package:flutter/material.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart';
import 'package:stream_chat_flutter_ai/stream_chat_flutter_ai.dart';
import 'package:uuid/uuid.dart';

import 'agent_service.dart';
import 'client_tools.dart';
import 'connection_banner.dart';
import 'conversation_view.dart';

/// The sample hardcodes OpenAI, the key the backend's `.env` sets up.
const _aiPlatform = 'openai';

class HomePage extends StatefulWidget {
  const HomePage({super.key, required this.client, required this.onThemeModeChanged});

  final StreamChatClient client;

  /// Called when the assistant asks the app to switch themes.
  final ValueChanged<ThemeMode> onThemeModeChanged;

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  final _agentService = AgentService();
  final _composerController = ChatComposerController(chatOptions: _chatOptions);
  Channel? _activeChannel;

  // The tool registry, shown in the client tools section below.
  late final _toolRegistry = AIToolRegistry()
    ..register(GreetUserTool(onGreet: _showGreeting))
    ..register(SetThemeModeTool(onChange: widget.onThemeModeChanged));

  /// Listens on the client, so it keeps working across conversations.
  late final ClientToolListener _toolListener;

  late final _channelListController = StreamChannelListController(
    client: widget.client,
    filter: Filter.in_('members', [widget.client.state.currentUser!.id]),
    limit: 30,
  );

  @override
  void initState() {
    super.initState();
    _toolListener = ClientToolListener(client: widget.client, registry: _toolRegistry);
  }

  @override
  void dispose() {
    _toolListener.dispose();
    _channelListController.dispose();
    _composerController.dispose();
    super.dispose();
  }

  // _showGreeting, _ensureAgentStarted, _showError, _setChannelTitle,
  // _sendMessage, _stopResponse, _openChannel and build follow below.
}

@override
Widget build(BuildContext context) {
  final activeChannel = _activeChannel;

  return Scaffold(
    drawer: _ConversationDrawer(
      controller: _channelListController,
      onChannelSelected: _openChannel,
    ),
    // The composer is in the body rather than `bottomNavigationBar`, because
    // only the body moves up when the keyboard opens.
    body: SafeArea(
      child: Column(
        children: [
          const ConnectionBanner(),
          Expanded(
            child: activeChannel == null
                ? _LandingView(onSuggestionTap: _sendMessage)
                : ConversationView(
                    key: ValueKey(activeChannel.cid),
                    channel: activeChannel,
                    onGeneratingChanged: (isGenerating) =>
                        _composerController.isGenerating = isGenerating,
                  ),
          ),
          ChatComposer(
            controller: _composerController,
            enableSpeechToText: true,
            onSendPressed: (text, option, attachments) =>
                _sendMessage(text, option: option, attachments: attachments),
            onStopPressed: _stopResponse,
          ),
        ],
      ),
    ),
  );
}

class _ConversationDrawer extends StatelessWidget {
  const _ConversationDrawer({required this.controller, required this.onChannelSelected});

  final StreamChannelListController controller;

  /// Called with the chosen channel, or `null` for a new chat.
  final ValueChanged<Channel?> onChannelSelected;

  @override
  Widget build(BuildContext context) {
    return Drawer(
      child: SafeArea(
        child: Column(
          children: [
            ListTile(
              leading: const Icon(Icons.add_comment_outlined),
              title: const Text('New chat'),
              onTap: () => onChannelSelected(null),
            ),
            const Divider(height: 1),
            Expanded(
              child: StreamChannelListView(
                controller: controller,
                itemBuilder: (context, items, index, defaultWidget) {
                  final channel = items[index];
                  return ListTile(
                    title: Text(channel.name ?? channel.id ?? ''),
                    onTap: () => onChannelSelected(channel),
                  );
                },
              ),
            ),
          ],
        ),
      ),
    );
  }
}

// Top of lib/src/home_page.dart (the sample defines six options)
const _chatOptions = [
  ChatOption(id: 'image', text: 'Create image', description: 'Visualize anything', icon: Icons.palette_outlined),
  ChatOption(id: 'research', text: 'Deep research', description: 'Get a detailed report', icon: Icons.travel_explore),
  ChatOption(id: 'search', text: 'Web search', description: 'Find real-time news and info', icon: Icons.public),
];

// Top of lib/src/home_page.dart (the sample defines six suggestions)
const _landingSuggestions = [
  'Create a painting in Renaissance-style',
  'Create a workout plan for resistance training',
  'Help me study vocabulary for an exam',
  'Top 5 restaurants in New York',
];

class _LandingView extends StatelessWidget {
  const _LandingView({required this.onSuggestionTap});

  final ValueChanged<String> onSuggestionTap;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        const Spacer(),
        AISuggestionsView(
          suggestions: _landingSuggestions,
          itemMaxWidth: 190,
          onSuggestionSelected: onSuggestionTap,
        ),
      ],
    );
  }
}

Future<void> _sendMessage(
  String text, {
  ChatOption? option,
  List<XFile> attachments = const [],
}) async {
  if (text.trim().isEmpty && attachments.isEmpty) return;

  var channel = _activeChannel;
  final isNewChannel = channel == null;
  if (channel == null) {
    channel = widget.client.channel(
      'messaging',
      id: const Uuid().v4(),
      extraData: {
        'members': [widget.client.state.currentUser!.id],
      },
    );
    await channel.watch();
    if (!mounted) return;
    setState(() => _activeChannel = channel);
    // Wait for the agent before sending: it only answers messages that
    // arrive after it has started.
    await _ensureAgentStarted(channel);
  }

  // `sendMessage` uploads the attachments itself.
  final messageAttachments = await Future.wait(
    attachments.map((file) => file.toAttachment(type: AttachmentType.image)),
  );
  await channel.sendMessage(
    Message(
      text: option == null ? text : '${option.text}: $text',
      attachments: messageAttachments,
    ),
  );

  if (isNewChannel) {
    unawaited(_setChannelTitle(channel, text.trim().isNotEmpty ? text : 'Photo'));
  }
}

Future<void> _ensureAgentStarted(Channel channel) async {
  final channelId = channel.id;
  if (channelId == null) return;

  try {
    await _agentService.startAgent(channelId, platform: _aiPlatform);
  } catch (e) {
    debugPrint('Failed to start the AI agent: $e');
    _showError(
      "Couldn't start the assistant. Is ai-sdk-sample running at ${AgentService.baseUrl}?",
    );
    return;
  }

  try {
    // Registering again for a channel the backend already knows is harmless,
    // and keeps it in sync with the tools this build has.
    await _agentService.registerTools(channelId, _toolRegistry.registrationPayloads());
  } catch (e) {
    debugPrint('Failed to register client tools: $e');
    _showError("The assistant is running, but can't use app actions like switching the theme.");
  }
}

void _showError(String message) {
  if (!mounted) return;
  ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text(message)));
}

Future<void> _setChannelTitle(Channel channel, String firstMessage) async {
  var title = firstMessage.length > 40 ? '${firstMessage.substring(0, 40)}…' : firstMessage;
  try {
    final summary = await _agentService.summarize(firstMessage, platform: _aiPlatform);
    if (summary != null && summary.trim().isNotEmpty) title = summary.trim();
  } catch (e) {
    debugPrint('Failed to summarize the title, using the message: $e');
  }

  try {
    await channel.updatePartial(set: {'name': title});
  } catch (e) {
    debugPrint('Failed to set the channel title: $e');
  }
}

Future<void> _stopResponse() async {
  try {
    await _activeChannel?.stopAIResponse();
  } catch (e) {
    debugPrint('Failed to stop the AI response: $e');
    _showError("Couldn't stop the reply.");
  }
}

void _openChannel(Channel? channel) {
  Navigator.of(context).pop(); // close the drawer
  setState(() => _activeChannel = channel);
  // The next conversation view reports its own state once it's listening.
  _composerController.isGenerating = false;
  if (channel == null) {
    _composerController.clear();
  } else {
    unawaited(_ensureAgentStarted(channel));
  }
}

// lib/src/connection_banner.dart
import 'package:flutter/material.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart';

/// A thin banner shown while the realtime connection is down.
///
/// Without it a dropped connection looks like the assistant misbehaving:
/// replies stay empty and client-tool invocations are missed, since both
/// arrive as channel events. Takes no space while connected.
class ConnectionBanner extends StatelessWidget {
  const ConnectionBanner({super.key});

  @override
  Widget build(BuildContext context) {
    final colors = Theme.of(context).colorScheme;

    return StreamConnectionStatusBuilder(
      statusBuilder: (context, status) {
        final banner = switch (status) {
          ConnectionStatus.connected => null,
          ConnectionStatus.connecting => (
              message: 'Reconnecting…',
              background: colors.secondaryContainer,
              foreground: colors.onSecondaryContainer,
            ),
          ConnectionStatus.disconnected => (
              message: 'Offline — new messages and AI actions may not arrive',
              background: colors.errorContainer,
              foreground: colors.onErrorContainer,
            ),
        };

        return AnimatedSize(
          duration: const Duration(milliseconds: 200),
          alignment: Alignment.topCenter,
          child: switch (banner) {
            null => const SizedBox(width: double.infinity),
            final banner => Container(
                width: double.infinity,
                color: banner.background,
                padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
                child: Row(
                  mainAxisAlignment: MainAxisAlignment.center,
                  children: [
                    if (status == ConnectionStatus.connecting) ...[
                      SizedBox.square(
                        dimension: 12,
                        child: CircularProgressIndicator(
                          strokeWidth: 2,
                          color: banner.foreground,
                        ),
                      ),
                      const SizedBox(width: 8),
                    ],
                    Flexible(
                      child: Text(
                        banner.message,
                        textAlign: TextAlign.center,
                        style: TextStyle(color: banner.foreground, fontSize: 13),
                      ),
                    ),
                  ],
                ),
              ),
          },
        );
      },
    );
  }
}

// lib/src/client_tools.dart
import 'dart:async';

import 'package:flutter/material.dart';
import 'package:stream_chat_flutter/stream_chat_flutter.dart';
import 'package:stream_chat_flutter_ai/stream_chat_flutter_ai.dart';

class GreetUserTool implements AIClientTool {
  const GreetUserTool({required this.onGreet});

  final VoidCallback onGreet;

  @override
  AIToolDefinition get definition => const AIToolDefinition(
        name: 'greetUser',
        description: 'Display a native greeting to the user',
        instructions: 'Use the greetUser tool when the user asks to be '
            'greeted. The tool shows a greeting alert in the Flutter app.',
      );

  @override
  List<AIToolAction> handleInvocation(AIToolInvocation invocation) => [onGreet];
}

class SetThemeModeTool implements AIClientTool {
  const SetThemeModeTool({required this.onChange});

  final ValueChanged<ThemeMode> onChange;

  @override
  AIToolDefinition get definition => const AIToolDefinition(
        name: 'setThemeMode',
        description: 'Switch the app between its light and dark theme',
        instructions: 'Use setThemeMode when the user asks for dark mode, '
            'light mode, or to change how the app looks.',
        parameters: {
          'type': 'object',
          'properties': {
            'mode': {
              'type': 'string',
              'enum': ['light', 'dark', 'system'],
              'description': 'The theme the app should switch to.',
            },
          },
          'required': ['mode'],
          'additionalProperties': false,
        },
      );

  @override
  List<AIToolAction> handleInvocation(AIToolInvocation invocation) {
    final mode = ThemeMode.values.asNameMap()[invocation.args['mode']];
    // Outside the schema's enum: better to do nothing than to guess.
    if (mode == null) return const [];
    return [() => onChange(mode)];
  }
}

late final _toolRegistry = AIToolRegistry()
  ..register(GreetUserTool(onGreet: _showGreeting))
  ..register(SetThemeModeTool(onChange: widget.onThemeModeChanged));

void _showGreeting() {
  if (!mounted) return;
  showDialog<void>(
    context: context,
    builder: (context) => AlertDialog(
      title: const Text('Greetings!'),
      content: const Text('👋 Hello there! The assistant asked me to greet you.'),
      actions: [
        TextButton(
          onPressed: () => Navigator.of(context).pop(),
          child: const Text('OK'),
        ),
      ],
    ),
  );
}

class ClientToolListener {
  ClientToolListener({required StreamChatClient client, required AIToolRegistry registry})
      : _registry = registry {
    _subscription = client.on(kClientToolInvocationEventType).listen(_onEvent);
  }

  final AIToolRegistry _registry;
  late final StreamSubscription<Event> _subscription;

  Future<void> _onEvent(Event event) async {
    final invocation = AIToolInvocation.tryParse(event.toClientToolPayload());
    if (invocation == null) return;

    final handled = await _registry.dispatch(invocation);
    if (!handled) debugPrint('No client tool registered as "${invocation.tool.name}"');
  }

  void dispose() => unawaited(_subscription.cancel());
}

extension EventClientToolPayload on Event {
  /// Rebuilds the JSON [AIToolInvocation.tryParse] reads.
  ///
  /// `Event` has no `tool` or `args` fields, so the SDK puts them in
  /// [extraData], while `cid` and `message_id` are regular fields.
  Map<String, Object?> toClientToolPayload() => {
        'type': type,
        'cid': cid,
        'message_id': messageId,
        ...extraData,
      };
}