flutter_agentic_ai 0.1.2

Embed intelligent, UI-aware AI agents in any Flutter app. Autonomous tap, type, scroll, and navigation using Flutter's semantics tree.

flutter_agentic_ai

Embed intelligent AI agents into any Flutter app — with a single widget.

flutter_agentic_ai lets users talk to your app in plain language and get things done. The agent navigates, taps, fills forms, and completes multi-step tasks — without you writing any automation code. Works out of the box on any production app with zero widget instrumentation.

---

✨ Features

• 🤖 Natural language tasks — users describe what they want, the agent does it
• 🗺️ Autonomous navigation — seamlessly routes through your app (currently requires go_router)
• 💬 Floating chat bar — draggable FAB + expandable panel, ready out of the box
• 🔄 Live thinking indicator — status overlay with cancel support
• 🛡️ Security guardrails — blacklist elements, mask PII, or disable UI control entirely
• 🌍 RTL / Arabic support — full right-to-left layout built in
• ⚡ Zero setup — no native code, no permissions, just wrap your MaterialApp
• 🔌 Gemini powered — built-in Gemini provider with proxy URL support for production

---

🚀 Quick Start

Important

Navigation Requirement: The autonomous navigation engine currently requires go_router. If your app uses standard Navigator or another routing package, the agent can still tap, type, and scroll, but it will not be able to autonomously route between screens.

1. Install

dependencies:
  flutter_agentic_ai: ^0.1.0

2. Wrap your app

import 'package:flutter_agentic_ai/flutter_agentic_ai.dart';

// Pass your API key via --dart-define (never hardcode it)
const apiKey = String.fromEnvironment('GEMINI_API_KEY');

return AiAgent(
  apiKey: apiKey,
  router: router,           // your GoRouter instance
  instructions: 'You are a helpful assistant for MyApp.',
  accentColor: Colors.deepPurple,
  onResult: (result) => debugPrint(result.message),
  child: MaterialApp.router(
    routerConfig: router,
    title: 'MyApp',
  ),
);

Run with:

flutter run --dart-define=GEMINI_API_KEY=your_key_here

---

📖 AiAgent Props

Provider

Prop	Type	Description
apiKey	String?	Gemini API key. Dev/prototyping only — use proxyUrl in production.
provider	AiProvider?	Pre-configured provider instance (takes precedence over apiKey).
proxyUrl	String?	Your backend proxy URL — keeps API keys off the device.
proxyHeaders	Map<String, String>?	Auth headers to send with proxy requests.
model	String?	Override the Gemini model (default: gemini-2.5-flash).

Behavior

Prop	Type	Default	Description
maxSteps	int	15	Maximum agent steps per task.
instructions	String?	—	System-level instructions for every interaction.
router	dynamic	—	go_router instance for deep navigation (currently the only supported router).
language	String	'en'	'en' or 'ar' — controls locale and RTL layout.
maxTokenBudget	int?	—	Auto-stop when token budget is exceeded.
maxCostUsd	double?	—	Auto-stop when estimated cost exceeds this value.
debug	bool	false	Enable verbose debug logging.

Lifecycle Callbacks

Prop	Type	Description
onResult	(ExecutionResult) → void	Called when the agent finishes a task.
onBeforeStep	(int stepCount) → Future<void>	Called before each agent step.
onAfterStep	(List<AgentStep>) → Future<void>	Called after each step.
onStatusUpdate	(String) → void	Live status text for custom UI integration.

Security

Prop	Type	Description
interactiveBlacklist	List<GlobalKey>?	Elements the AI must not interact with.
interactiveWhitelist	List<GlobalKey>?	If set, AI can only interact with these elements.
transformScreenContent	(String) → Future<String>	Mask PII before the AI sees screen content.
enableUiControl	bool	false for knowledge-only mode. Default: true.

UI

Prop	Type	Description
accentColor	Color?	Accent color for FAB and send button.
theme	AgentChatBarTheme?	Full chat bar theme override.
showChatBar	bool	Show/hide the floating chat bar. Default: true.

---

🛡️ Security Guardrails

Block sensitive UI areas

final _paymentKey = GlobalKey();

AiAgent(
  interactiveBlacklist: [_paymentKey],
  child: Scaffold(
    body: Container(key: _paymentKey, child: CreditCardForm()),
  ),
);

Mask PII before the AI sees it

AiAgent(
  transformScreenContent: (content) async {
    return content
      .replaceAll(RegExp(r'\b\d{16}\b'), '****-****-****-****')
      .replaceAll(RegExp(r'[\w.]+@[\w.]+'), '[email]');
  },
  child: ...,
)

Knowledge-only mode

AiAgent(
  enableUiControl: false,
  instructions: 'Answer questions about the app only.',
  child: ...,
)

Production proxy

AiAgent(
  proxyUrl: 'https://api.myapp.com/ai',
  proxyHeaders: {'Authorization': 'Bearer $userToken'},
  child: ...,
)

⚠️ Using apiKey directly in a release build will log a security warning. Use proxyUrl in production.

---

🎨 Custom Theme

AiAgent(
  theme: AgentChatBarTheme(
    primaryColor: Colors.indigo,
    backgroundColor: const Color(0xFF1A1A2E),
    textColor: Colors.white,
  ),
  child: ...,
)

---

🪝 Access the Agent Anywhere

Trigger the agent from any widget in the tree:

final agent = AiAgentScope.of(context);

ElevatedButton(
  onPressed: () => agent.send('Add the first item to cart'),
  child: const Text('Let AI do it'),
);

---

⚙️ Custom Actions

Register custom Dart functions the agent can call:

actionRegistry.register(AgentAction(
  name: 'open_support_chat',
  description: 'Opens the in-app support chat',
  parameters: {},
  handler: (_) async {
    SupportChat.show();
    return ActionResult(success: true);
  },
));

---

📦 Requirements

• Flutter >=3.0.0
• Dart >=3.0.0
• go_router (required for autonomous navigation)
• Gemini API key — get one free at Google AI Studio

---

📄 License

MIT © 2025 MobileAI