install · 60 seconds

One pubspec line.

Add the dep, paste the snippet, ship.

  • iOS 12+
  • Android API 21+
  • macOS
  • Dart 3.10+ · Flutter 3.38+

1. Add the dependency

pubspec.yaml
dependencies:
  agentlib: ^1.1.0
terminal
flutter pub get

2. Set your API key (cloud) — or skip it (on-device)

If you want to use Anthropic, OpenAI, or Google, pass the key as a dart-define so it's not in your source.

terminal
flutter run -d  --dart-define=ANTHROPIC_API_KEY=sk-ant-...

If you only want on-device, no key is needed — just enable the providers you want in ModelRoute.preferOnDevice([...]).

3. Paste the agent

lib/main.dart
import 'package:agentlib/agentlib.dart';
import 'package:flutter/material.dart';
import 'package:path_provider/path_provider.dart';

Future main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const HelloAgentApp());
}

class HelloAgentApp extends StatelessWidget {
  const HelloAgentApp({super.key});
  @override
  Widget build(BuildContext ctx) => const MaterialApp(home: _Screen());
}

class _Screen extends StatefulWidget { const _Screen(); @override State<_Screen> createState() => _State(); }

class _State extends State<_Screen> {
  final _out = StringBuffer();

  Future _run() async {
    final docs = await getApplicationDocumentsDirectory();
    final vfs = Vfs()
      ..mount('/workspace', WorkspaceMount(docs))
      ..mount('/scratch', ScratchMount());

    final agent = AgentSpec(
      name: 'hello',
      instructions: 'You are a helpful mobile assistant.',
      model: AnthropicProvider(
        apiKey: const String.fromEnvironment('ANTHROPIC_API_KEY'),
      ),
    );

    final run = Runner.runStreamed(
      agent.toRunConfig(vfs: vfs, threadId: 'hello'),
      input: 'In one sentence: what is agentlib?',
    );
    await for (final e in run.events) {
      if (e is TextDelta) setState(() => _out.write(e.delta));
    }
  }

  @override
  Widget build(BuildContext ctx) => Scaffold(
    appBar: AppBar(title: const Text('agentlib hello')),
    body: Padding(padding: const EdgeInsets.all(16), child: Text(_out.toString())),
    floatingActionButton: FloatingActionButton(onPressed: _run, child: const Icon(Icons.play_arrow)),
  );
}

4. Run

terminal
flutter run -d ios
# or
flutter run -d android

Platform support

  • iOS: 12+ for the base SDK; iOS 19+ for FoundationModelsProvider.
  • Android: API 21+ (Lollipop, 2014). Gemini Nano needs Pixel 8 / S24 or newer; MediaPipe runs on Android 12+.
  • macOS: works for dev; production focus is mobile.
  • Dart: ≥ 3.10.0. Flutter: ≥ 3.38.1.

Next steps

  • Primitives — read the 8 load-bearing APIs in depth.
  • On-device — wire up Foundation Models / Gemini Nano / Fllama.
  • Sh mini-shell — give your agent a Unix-shaped tool surface.
  • GitHub — examples, issues, source.
next

Now build something.

The /example folder in the repo has five quickstarts: hello_agent, multi_tool, on_device, voice, and mobile_automation.