agentic_flutter #

The agentic framework, ready to use in a Flutter app. One import gives you every layer, plus the pieces that only make sense in an app: a runtime that lives as long as the widget tree, cancellation tied to the app lifecycle, device capabilities as tools, somewhere safe to keep a key, and widgets for chat, approval and traces.

import 'package:agentic_flutter/agentic_flutter.dart';

void main() {
  final runtime = AgenticRuntime(
    tools: ToolRegistry()..register(myTool),
    backgroundPolicy: BackgroundPolicy.cancelOnPause,
  );

  runApp(AgenticScope(runtime: runtime, child: const MyApp()));
}

// Anywhere below the scope:
final controller = AgentChatController(
  agent: ToolCallingAgent(
    info: AgentInfo(name: 'assistant', description: 'Helps with things.'),
    model: OpenAiCompatibleChatModel.openAi(apiKey: key),
    tools: context.agenticTools.all,
  ),
  runtime: context.agentic,
);

AgentChatView(controller: controller);

What is here #

Five decisions worth knowing about #

No plugin dependencies. Location, camera, secure storage and speech each mean a platform dependency, a permissions story and an upgrade treadmill. Adding them here would put all of that into every app that only calls a hosted model. So platform_tools and SecretStore are ports over callbacks you supply: a few lines in your app, and nothing in anybody else's build.

Cancellation is tied to the lifecycle, not just to the screen. A server process runs until its work is done; a phone suspends the app mid-run. An agent loop that nothing asks to stop is either billing for an answer nobody will read or resuming hours later against a screen that no longer exists. BackgroundPolicy decides which of those you get, and the default — cancelOnDetach — survives a brief switch away without leaving a model call running behind a dying process.

The runtime is inherited, not global. A singleton is one runtime, which is fine until a widget test wants a fake, a second screen wants a different tool set, or two tests in a suite inherit each other's disposed event bus. All three disappear when it comes down the tree.

Approval fails closed, and the sheet is written so it stays that way. agentic_tools already denies a gated tool with no handler configured. So the risk here is a sheet that says yes by accident: dismissing denies, the arguments the model actually proposed are shown rather than a summary, the allow button is not autofocused, and a handler with no navigator to ask through denies rather than allowing.

Widgets are a starting point, not a design system. AgentChatView is a working chat screen — transcript, composer, activity line, stop button, error rendering. Every real product replaces it. The controller and the parts it is built from (ChatEntryTile, ChatComposer) are public precisely so you can keep the state and throw the pixels away.

API keys: read this before shipping #

An API key compiled into a Flutter app is readable by anyone who downloads it. Not "hard to find" — an APK is a zip file. The same goes for --dart-define, an asset, or a bundled .env. There are two honest answers:

1. Do not ship the key. Put a small service between the app and the provider, authenticate the user to it, and let it hold the provider key. This is the only approach that is actually safe.
2. Let the user supply their own key — normal for developer tools. Then it needs somewhere safe on the device, which is what SecretStore is for.

The package ships the port and an in-memory implementation; the keychain adapter is five lines in your app over flutter_secure_storage. DartDefineSecretStore exists and refuses to serve unlisted keys in release builds, because pretending the option does not exist does not stop people using it.

Why an umbrella package #

An application should not have to know that AgentSession lives in agentic_agents and MetadataFilter in agentic_vector. A plugin should: a package that adds one tool depends on agentic_tools and nothing else, and stays small. Applications take the umbrella; extensions take the layer they extend.

Cost and performance notes #

• BackgroundPolicy.cancelOnPause is the setting that bounds cost on a phone. Users switch away constantly; without it, every one of those is a run that keeps going.
• Resize photos before returning them. A 4 MB camera JPEG is ~5.3 MB of base64 and a four-figure token count. 1024 pixels on the long edge answers almost any question a model is asked about an image; cameraTool enforces a ceiling and says so rather than sending it.
• EventRecorder is bounded at 500 events by default and reports what it dropped. An unbounded trace panel is a memory leak that gets the app killed.
• Logging is debug-only unless you opt in. A framework that logs prompts in release has published them to the platform log.

Common mistakes #

Documentation #

• Example — a working chat app: cd example && flutter run
• Architecture
• Individual layers: agentic_core, agentic_tools, agentic_llm, agentic_agents, agentic_memory, agentic_workflow, agentic_vector, agentic_rag, agentic_mcp