Full-Stack Agentic Dart: Building End-to-End Typed AI Agents with Genkit Dart & Shelf

# macOS / Linux / Git Bash
mkdir -p agentic_commerce_workspace/packages/shared_contracts/lib
mkdir -p agentic_commerce_workspace/packages/agent_server/lib/flows
mkdir -p agentic_commerce_workspace/packages/agent_server/lib/tools
mkdir -p agentic_commerce_workspace/packages/agent_server/bin
cd agentic_commerce_workspace

# Windows PowerShell
New-Item -ItemType Directory -Force -Path "agentic_commerce_workspace\packages\shared_contracts\lib"
New-Item -ItemType Directory -Force -Path "agentic_commerce_workspace\packages\agent_server\lib\flows"
New-Item -ItemType Directory -Force -Path "agentic_commerce_workspace\packages\agent_server\lib\tools"
New-Item -ItemType Directory -Force -Path "agentic_commerce_workspace\packages\agent_server\bin"
Set-Location agentic_commerce_workspace

name: shared_contracts
description: Shared Schemantic data contracts for Genkit server and Flutter client.
version: 1.0.0
publish_to: 'none'

environment:
  sdk: ^3.12.0

dependencies:
  schemantic: ^1.0.0

dev_dependencies:
  build_runner: ^2.16.2
  lints: ^6.1.0
  schemantic_builder: ^1.0.0

import 'package:schemantic/schemantic.dart';

part 'agent_contracts.g.dart';

@Schema()
abstract class $OrderAuditInput {
  String get orderId;
  String get sku;

  @IntegerField(
    minimum: 1,
    description: 'Requested unit count for the wholesale order',
  )
  int get quantity;

  @StringField(
    minLength: 2,
    enumValues: ['EAST_AFRICA', 'CENTRAL_AFRICA', 'WEST_AFRICA'],
    description: 'Target fulfillment corridor',
  )
  String get region;

  String? get partnerCode;
}

@Schema()
abstract class $OrderAuditResult {
  String get orderId;
  bool get approved;

  @StringField(
    enumValues: ['APPROVED', 'HOLD_QUOTA_EXCEEDED', 'REJECTED_OUT_OF_STOCK'],
  )
  String get status;

  @IntegerField(
    minimum: 0,
    description: 'Verified units allocated from regional warehouse',
  )
  int get allocatedQuantity;

  double get finalTotalUsd;
  String get reasoningSummary;
}

@Schema()
abstract class $InventoryLookupInput {
  String get sku;
  String get region;

  @IntegerField(minimum: 1)
  int get requestedUnits;
}

@Schema()
abstract class $PartnerDiscountInput {
  String get orderId;
  String get partnerCode;

  @IntegerField(
    minimum: 1,
    maximum: 50,
    description: 'Requested partner discount percentage (1 to 50)',
  )
  int get requestedDiscountPct;
}

cd packages/shared_contracts
dart pub get
dart run build_runner build
dart analyze
cd ../..

name: agent_server
description: Genkit Dart + Shelf Agentic Backend Server.
version: 1.0.0
publish_to: 'none'

environment:
  sdk: ^3.12.0

dependencies:
  genkit: ^1.0.1
  genkit_google_genai: ^1.0.1
  genkit_middleware: ^1.0.1
  genkit_shelf: ^1.0.1
  schemantic: ^1.0.0
  shared_contracts:
    path: ../shared_contracts
  shelf: ^1.4.2
  shelf_router: ^1.1.4

dev_dependencies:
  lints: ^6.1.0

import 'package:genkit/genkit.dart';
import 'package:genkit_google_genai/genkit_google_genai.dart';
import 'package:shared_contracts/agent_contracts.dart';

/// Defines a strictly typed order audit flow returning [OrderAuditResult].
Flow<OrderAuditInput, OrderAuditResult, void, void> defineAuditOrderFlow(
  Genkit ai,
) {
  return ai.defineFlow(
    name: 'auditOrder',
    inputSchema: OrderAuditInput.$schema,
    outputSchema: OrderAuditResult.$schema,
    fn: (OrderAuditInput input, _) async {
      final response = await ai.generate(
        model: googleAI.gemini('gemini-2.5-flash'),
        prompt: '''
You are a principal wholesale order compliance auditor.
Audit the following order request using the authoritative server tool `verifyInventoryAndQuota`:
- Order ID: ${input.orderId}
- SKU: ${input.sku}
- Requested Quantity: ${input.quantity}
- Target Corridor: ${input.region}
- Partner Code: ${input.partnerCode ?? 'NONE'}

Rules:
1. Always call `verifyInventoryAndQuota` first to obtain the authoritative stock, quota, and unit price.
2. If the SKU is out of stock (availableUnits < requestedUnits), set approved=false, status='REJECTED_OUT_OF_STOCK', allocatedQuantity=0, finalTotalUsd=0.
3. If requested quantity exceeds maxOrderQuota, set approved=false, status='HOLD_QUOTA_EXCEEDED', allocatedQuantity=maxOrderQuota, and compute finalTotalUsd for the capped allocation.
4. Otherwise set approved=true, status='APPROVED', allocatedQuantity=quantity, and compute finalTotalUsd = quantity * unitPriceUsd.
''',
        toolNames: ['verifyInventoryAndQuota'],
        outputSchema: OrderAuditResult.$schema,
      );

      final structuredOutput = response.output;
      if (structuredOutput == null) {
        throw StateError(
          'Model failed to produce a valid OrderAuditResult schema payload.',
        );
      }
      return structuredOutput;
    },
  );
}

import 'package:genkit/genkit.dart';
import 'package:shared_contracts/agent_contracts.dart';

/// Authoritative server-side catalog and regional quota ledger.
/// The mobile client never sends prices or quota limits; the server resolves them.
const Map<String, Map<String, Object>> _serverInventoryCatalog = {
  'SOLAR-INV-3KW': {
    'unitPriceUsd': 420.0,
    'stockByRegion': {
      'EAST_AFRICA': 45,
      'CENTRAL_AFRICA': 18,
      'WEST_AFRICA': 30,
    },
    'maxOrderQuota': 20,
  },
  'LFP-BATT-5KWH': {
    'unitPriceUsd': 680.0,
    'stockByRegion': {
      'EAST_AFRICA': 12,
      'CENTRAL_AFRICA': 6,
      'WEST_AFRICA': 15,
    },
    'maxOrderQuota': 10,
  },
};

/// Registers authoritative inventory and partner discount tools on [ai].
void registerInventoryTools(Genkit ai) {
  ai.defineTool(
    name: 'verifyInventoryAndQuota',
    description:
        'Checks authoritative regional warehouse stock, unit price in USD, '
        'and maximum per-order quota for a given SKU and region.',
    inputSchema: InventoryLookupInput.$schema,
    fn: (InventoryLookupInput input, _) async {
      final skuRecord = _serverInventoryCatalog[input.sku.toUpperCase()];
      if (skuRecord == null) {
        return ToolResult.response({
          'found': false,
          'sku': input.sku,
          'error': 'SKU not found in authoritative catalog.',
        });
      }

      final stockMap = skuRecord['stockByRegion']! as Map<String, int>;
      final availableUnits = stockMap[input.region] ?? 0;
      final maxQuota = skuRecord['maxOrderQuota']! as int;
      final unitPriceUsd = skuRecord['unitPriceUsd']! as double;

      return ToolResult.response({
        'found': true,
        'sku': input.sku.toUpperCase(),
        'region': input.region,
        'availableUnits': availableUnits,
        'maxOrderQuota': maxQuota,
        'unitPriceUsd': unitPriceUsd,
        'withinQuota': input.requestedUnits <= maxQuota,
        'sufficientStock': input.requestedUnits <= availableUnits,
      });
    },
  );

  ai.defineTool(
    name: 'applyPartnerDiscount',
    description:
        'Applies a privileged partner discount percentage to an order. '
        'Sensitive state-mutating tool protected by human-in-the-loop approval.',
    inputSchema: PartnerDiscountInput.$schema,
    fn: (PartnerDiscountInput input, _) async {
      final cappedPct = input.requestedDiscountPct.clamp(1, 25);
      return ToolResult.response(
        'Partner discount of $cappedPct% authorized for order '
        '${input.orderId} under partner code ${input.partnerCode}.',
      );
    },
  );
}

import 'package:genkit/genkit.dart';
import 'package:genkit_google_genai/genkit_google_genai.dart';
import 'package:genkit_middleware/genkit_middleware.dart';
import 'package:schemantic/schemantic.dart';
import 'package:shared_contracts/agent_contracts.dart';

/// Defines a flow guarded by `toolApproval` middleware.
/// Read-only `verifyInventoryAndQuota` runs automatically, while
/// `applyPartnerDiscount` triggers `FinishReason.interrupted` for supervisor review.
Flow<OrderAuditInput, String, void, void> defineGuardedDiscountFlow(
  Genkit ai, {
  required Future<bool> Function(ToolRequestPart interrupt) onSupervisorReview,
}) {
  return ai.defineFlow(
    name: 'guardedDiscountAudit',
    inputSchema: OrderAuditInput.$schema,
    outputSchema: SchemanticType.string(),
    fn: (OrderAuditInput input, _) async {
      final response = await ai.generate(
        model: googleAI.gemini('gemini-2.5-flash'),
        prompt: '''
Verify inventory for Order ${input.orderId} (SKU: ${input.sku}, qty: ${input.quantity}, region: ${input.region}).
If partnerCode (${input.partnerCode ?? 'NONE'}) is present, call `applyPartnerDiscount` with a 15% partner discount.
''',
        toolNames: ['verifyInventoryAndQuota', 'applyPartnerDiscount'],
        use: [
          // Read-only lookup is pre-approved; state-mutating discount requires approval
          toolApproval(approved: ['verifyInventoryAndQuota']),
        ],
      );

      if (response.finishReason == FinishReason.interrupted) {
        final interrupt = response.interrupts.first;
        final isApproved = await onSupervisorReview(interrupt);

        if (!isApproved) {
          return 'Order ${input.orderId}: Partner discount tool call '
              '(${interrupt.toolRequest.name}) rejected by supervisor.';
        }

        final resumedResponse = await ai.generate(
          model: googleAI.gemini('gemini-2.5-flash'),
          messages: response.messages,
          toolChoice: ToolChoice.none,
          interruptRestart: [
            ToolRequestPart(
              toolRequest: interrupt.toolRequest,
              metadata: {
                ...?interrupt.metadata,
                'tool-approved': true,
              },
            ),
          ],
        );

        return resumedResponse.text;
      }

      return response.text;
    },
  );
}

import 'dart:io';
import 'package:genkit/genkit.dart';
import 'package:genkit_google_genai/genkit_google_genai.dart';
import 'package:genkit_middleware/genkit_middleware.dart';
import 'package:genkit_shelf/genkit_shelf.dart';
import 'package:schemantic/schemantic.dart';
import 'package:shared_contracts/agent_contracts.dart';
import 'package:shelf/shelf.dart';
import 'package:shelf/shelf_io.dart' as io;
import 'package:shelf_router/shelf_router.dart';

import 'package:agent_server/flows/audit_flow.dart';
import 'package:agent_server/flows/guarded_action_flow.dart';
import 'package:agent_server/tools/inventory_tools.dart';

Future<void> main() async {
  final apiKey = Platform.environment['GEMINI_API_KEY'];
  if (apiKey == null || apiKey.isEmpty) {
    stderr.writeln('ERROR: GEMINI_API_KEY environment variable is not set.');
    exit(1);
  }

  // 1. Initialize Genkit with Google AI and Middleware plugins
  final ai = Genkit(
    plugins: [
      googleAI(),
      FilesystemPlugin(),
      SkillsPlugin(),
      ToolApprovalPlugin(),
    ],
  );

  // 2. Register authoritative server-side tools
  registerInventoryTools(ai);

  // 3. Register typed and guarded flows
  final auditOrderFlow = defineAuditOrderFlow(ai);
  final guardedDiscountFlow = defineGuardedDiscountFlow(
    ai,
    onSupervisorReview: (interrupt) async {
      stdout.writeln(
        '[HITL Supervisor] Intercepted tool: ${interrupt.toolRequest.name} '
        'with input: ${interrupt.toolRequest.input}',
      );
      return true;
    },
  );

  // 4. Define a real-time streaming flow with chunked narration + final typed output
  final streamOrderAuditFlow = ai.defineFlow(
    name: 'streamOrderAudit',
    inputSchema: OrderAuditInput.$schema,
    outputSchema: OrderAuditResult.$schema,
    streamSchema: SchemanticType.string(),
    fn: (OrderAuditInput input, context) async {
      final stream = ai.generateStream(
        model: googleAI.gemini('gemini-2.5-flash'),
        prompt: '''
Stream a concise, real-time compliance log while auditing Order ${input.orderId}
(SKU: ${input.sku}, quantity: ${input.quantity}, corridor: ${input.region}).
Call `verifyInventoryAndQuota` to inspect stock and quota constraints.
''',
        toolNames: ['verifyInventoryAndQuota'],
      );

      await for (final chunk in stream) {
        if (chunk.text.isNotEmpty) {
          context.sendChunk(chunk.text);
        }
      }

      return auditOrderFlow(input);
    },
  );

  // 5. Mount Genkit flows onto a custom Shelf Router alongside health probes
  // (Alternatively, call `await startFlowServer(flows: [...], port: 3400);`)
  final router = Router()
    ..get('/healthz', (Request req) => Response.ok('{"status":"ok"}'))
    ..post('/auditOrder', shelfHandler(auditOrderFlow))
    ..post('/streamOrderAudit', shelfHandler(streamOrderAuditFlow))
    ..post('/guardedDiscountAudit', shelfHandler(guardedDiscountFlow));

  final handler = const Pipeline()
      .addMiddleware(logRequests())
      .addHandler(router.call);

  final port = int.parse(Platform.environment['PORT'] ?? '3400');
  final server = await io.serve(handler, InternetAddress.anyIPv4, port);
  stdout.writeln(
    'Genkit Shelf Agent Server listening on http://${server.address.host}:${server.port}',
  );
}

name: flutter_client
description: Flutter streaming client for Genkit Dart Shelf server.
version: 1.0.0
publish_to: 'none'

environment:
  sdk: ^3.12.0

dependencies:
  flutter:
    sdk: flutter
  genkit: ^1.0.1
  schemantic: ^1.0.0
  shared_contracts:
    path: ../../packages/shared_contracts

dev_dependencies:
  flutter_lints: ^5.0.0
  flutter_test:
    sdk: flutter

import 'package:flutter/material.dart';
import 'package:genkit/client.dart';
import 'package:schemantic/schemantic.dart';
import 'package:shared_contracts/agent_contracts.dart';

void main() {
  runApp(const AgenticAuditApp());
}

class AgenticAuditApp extends StatelessWidget {
  const AgenticAuditApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Genkit Dart Agentic Auditor',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorSchemeSeed: const Color(0xFF0284C7),
        useMaterial3: true,
      ),
      home: const OrderAuditScreen(),
    );
  }
}

class OrderAuditScreen extends StatefulWidget {
  const OrderAuditScreen({super.key});

  @override
  State<OrderAuditScreen> createState() => _OrderAuditScreenState();
}

class _OrderAuditScreenState extends State<OrderAuditScreen> {
  static const String _serverBaseUrl = String.fromEnvironment(
    'GENKIT_SERVER_URL',
    defaultValue: 'http://localhost:3400',
  );

  late final _streamOrderAuditAction = defineRemoteAction(
    url: '$_serverBaseUrl/streamOrderAudit',
    inputSchema: OrderAuditInput.$schema,
    outputSchema: OrderAuditResult.$schema,
    streamSchema: SchemanticType.string(),
  );

  String _selectedSku = 'SOLAR-INV-3KW';
  String _selectedRegion = 'EAST_AFRICA';
  int _quantity = 12;
  bool _isStreaming = false;
  String _liveNarration = '';
  OrderAuditResult? _finalResult;
  String? _errorMessage;

  Future<void> _runStreamingAudit() async {
    setState(() {
      _isStreaming = true;
      _liveNarration = '';
      _finalResult = null;
      _errorMessage = null;
    });

    final requestInput = OrderAuditInput(
      orderId: 'ORD-${DateTime.now().millisecondsSinceEpoch % 100000}',
      sku: _selectedSku,
      quantity: _quantity,
      region: _selectedRegion,
      partnerCode: 'SOLAR-PARTNER-UG',
    );

    try {
      final stream = _streamOrderAuditAction.stream(input: requestInput);

      await for (final chunk in stream) {
        if (!mounted) return;
        setState(() {
          _liveNarration += chunk;
        });
      }

      final typedResult = await stream.onResult;
      if (!mounted) return;
      setState(() {
        _finalResult = typedResult;
      });
    } catch (e) {
      if (!mounted) return;
      setState(() {
        _errorMessage = e.toString();
      });
    } finally {
      if (mounted) {
        setState(() {
          _isStreaming = false;
        });
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    final result = _finalResult;
    return Scaffold(
      appBar: AppBar(
        title: const Text('Genkit Dart | Full-Stack Order Auditor'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            Row(
              children: [
                Expanded(
                  child: DropdownButtonFormField<String>(
                    initialValue: _selectedSku,
                    decoration: const InputDecoration(labelText: 'Catalog SKU'),
                    items: const [
                      DropdownMenuItem(
                        value: 'SOLAR-INV-3KW',
                        child: Text('SOLAR-INV-3KW (3kW Inverter)'),
                      ),
                      DropdownMenuItem(
                        value: 'LFP-BATT-5KWH',
                        child: Text('LFP-BATT-5KWH (5kWh Battery)'),
                      ),
                    ],
                    onChanged: _isStreaming
                        ? null
                        : (v) => setState(() => _selectedSku = v!),
                  ),
                ),
                const SizedBox(width: 12),
                Expanded(
                  child: DropdownButtonFormField<String>(
                    initialValue: _selectedRegion,
                    decoration: const InputDecoration(labelText: 'Corridor'),
                    items: const [
                      DropdownMenuItem(
                        value: 'EAST_AFRICA',
                        child: Text('EAST_AFRICA'),
                      ),
                      DropdownMenuItem(
                        value: 'CENTRAL_AFRICA',
                        child: Text('CENTRAL_AFRICA'),
                      ),
                      DropdownMenuItem(
                        value: 'WEST_AFRICA',
                        child: Text('WEST_AFRICA'),
                      ),
                    ],
                    onChanged: _isStreaming
                        ? null
                        : (v) => setState(() => _selectedRegion = v!),
                  ),
                ),
              ],
            ),
            const SizedBox(height: 12),
            Row(
              children: [
                Expanded(
                  child: Slider(
                    value: _quantity.toDouble(),
                    min: 1,
                    max: 30,
                    divisions: 29,
                    label: '$_quantity units',
                    onChanged: _isStreaming
                        ? null
                        : (v) => setState(() => _quantity = v.round()),
                  ),
                ),
                Text(
                  'Qty: $_quantity',
                  style: const TextStyle(fontWeight: FontWeight.w700),
                ),
              ],
            ),
            const SizedBox(height: 8),
            FilledButton(
              onPressed: _isStreaming ? null : _runStreamingAudit,
              child: Text(
                _isStreaming
                    ? 'Streaming Server Audit...'
                    : 'Run Typed Genkit Audit Flow',
              ),
            ),
            const SizedBox(height: 16),
            if (_errorMessage != null)
              Container(
                padding: const EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: const Color(0xFFFEE2E2),
                  border: Border.all(color: const Color(0xFFDC2626)),
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Text(
                  _errorMessage!,
                  style: const TextStyle(color: Color(0xFF991B1B)),
                ),
              ),
            Expanded(
              child: SingleChildScrollView(
                child: Column(
                  crossAxisAlignment: CrossAxisAlignment.stretch,
                  children: [
                    if (_liveNarration.isNotEmpty) ...[
                      const Text(
                        'Live Stream Chunks (streamSchema: String):',
                        style: TextStyle(fontWeight: FontWeight.bold),
                      ),
                      const SizedBox(height: 6),
                      SelectableText(_liveNarration),
                      const Divider(height: 28),
                    ],
                    if (result != null)
                      Container(
                        padding: const EdgeInsets.all(14),
                        decoration: BoxDecoration(
                          color: const Color(0xFFE0F2FE),
                          border: Border.all(color: const Color(0xFF0284C7)),
                          borderRadius: BorderRadius.circular(10),
                        ),
                        child: Column(
                          crossAxisAlignment: CrossAxisAlignment.start,
                          children: [
                            Text(
                              'Typed OrderAuditResult (${result.status})',
                              style: const TextStyle(
                                fontWeight: FontWeight.w700,
                                fontSize: 16,
                              ),
                            ),
                            const SizedBox(height: 6),
                            Text('Order ID: ${result.orderId}'),
                            Text('Approved: ${result.approved}'),
                            Text('Allocated Units: ${result.allocatedQuantity}'),
                            Text(
                              'Authoritative Total: \$${result.finalTotalUsd.toStringAsFixed(2)} USD',
                            ),
                            const SizedBox(height: 6),
                            Text(result.reasoningSummary),
                          ],
                        ),
                      ),
                  ],
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

# 1. Verify shared contracts package
cd packages/shared_contracts
dart analyze

# 2. Verify Genkit Shelf server package
cd ../agent_server
dart pub get
dart analyze

# 3. Export your Gemini API key (macOS / Linux / Git Bash)
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
# Or in Windows PowerShell:
# $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

# 4. Start the Dart server attached to the Genkit Developer UI (http://localhost:4000)
genkit start -- dart run bin/server.dart

# 5. In a second terminal, verify and run the Flutter client
cd ../../apps/flutter_client
flutter pub get
flutter analyze
flutter run