Flutter Agent Starter

This starter app template for LiveKit Agents provides a simple voice interface using the LiveKit Flutter SDK. It supports voice, transcriptions, live video input, and virtual avatars.

This template is compatible with iOS, macOS, Android, and web. It is free for you to use or modify as you see fit.

Getting started

Run the following command to automatically clone this template and connect it to LiveKit Cloud.

lk app create --template agent-starter-flutter

This will create a new Flutter project in the current directory. Install dependencies and run the app:

flutter pub get
flutter run

Note: You may need to configure signing certificates in Xcode if building to a real iOS device.

The app is configured to connect to the LiveKit homepage agent by default, which you can also try at livekit.com. To point the app at your own agent (see Connect to your agent).

Note

To setup without the LiveKit CLI, clone the repository and then create the assets/.env file manually from a copy of .env.example. The env file is optional: without any configuration, the app connects to a default agent — the same one featured on the LiveKit homepage — so you can try it out right away.

Connect to your agent

To switch from the default agent to your own, you first need a LiveKit agent to speak with. For a no-code setup, use the Agent Builder. For more customization, try our starter agent for Python, Node.js, or create your own from scratch.

Second, you need a token server. For development, the easiest option is the development token server: turn on the Development token server switch on the Settings page in LiveKit Cloud and copy the Token server ID.

Then fill the LIVEKIT_TOKEN_SERVER_ID in your assets/.env:

LIVEKIT_TOKEN_SERVER_ID=<your-token-server-id>

or modify lib/controllers/app_ctrl.dart to replace the DevelopmentTokenSource with your own token source implementation (development-only hardcoded credentials are also supported there).

Note

The development token server is for prototyping only — any client can request a token with any permissions. See Token generation in production before you ship.

This setting was previously called the sandbox token server, and LIVEKIT_SANDBOX_ID is still accepted as a fallback for existing .env files.

Feature overview

This starter app supports several features of the agents framework and is intended as a base you can adapt for your own use case.

Text, video, and voice input

This app supports:

• Voice: send microphone audio to your agent. Requires microphone permissions.
• Text: send text input using the message bar.
• Video: optionally share camera and/or screen share tracks to the room so your agent can process visual input (requires an agent/model that supports it).

Related docs:

• Voice agents: https://docs.livekit.io/agents/start/voice-ai/
• Text: https://docs.livekit.io/agents/build/text/
• Vision/video: https://docs.livekit.io/agents/build/vision/#video
• Screen share: https://docs.livekit.io/home/client/tracks/screenshare/

If you have trouble with screen sharing, refer to the docs linked above for more setup instructions.

Session

The app is built around two core concepts:

• livekit_client.Session: connects to LiveKit, dispatches/observes the agent, and provides a message history via session.messages as well as helpers like session.sendText(...).
• livekit_components.RoomContext / MediaDeviceContext: manages local media tracks (microphone, camera, screen share) and their lifecycle.

Preconnect audio buffer

This app enables preConnectAudio by default to capture and buffer audio before the room connection completes. This allows the connection to appear "instant" from the user's perspective and makes the app more responsive.

To disable this feature, set preConnectAudio to false in SessionOptions when creating the Session (see lib/controllers/app_ctrl.dart).

Virtual avatar / agent video

If your agent publishes a video track (for example via a virtual avatar integration), the app renders the agent's video when available and falls back to an audio visualizer otherwise.

Token generation in production

In a production environment, you will be responsible for developing a solution to generate tokens for your users that integrates with your authentication system.

You should replace the DevelopmentTokenSource in lib/controllers/app_ctrl.dart with an EndpointTokenSource or your own TokenSourceFixed / TokenSourceConfigurable implementation. You can also use .cached() to cache valid tokens and avoid unnecessary token requests.

Running on Simulator / Emulator

To use this template with video (or screen sharing) input, you may need to run the app on a physical device depending on platform and simulator/emulator capabilities. Testing on Simulator/Emulator will still support voice and text modes.

Contributing

This template is open source and we welcome contributions! Please open a PR or issue through GitHub, and don't forget to join us in the LiveKit Community Slack!