DEV Community: Esra Kadah

I approved the order. Then my Genkit Dart agent forgot its own tool.

Esra Kadah — Tue, 27 Oct 2026 09:54:50 +0000

My agent asked me "can I order this part?". I said yes. And the answer came back as a failure:

finishReason: FinishReason.failed
finishMessage: Tool order_part not found

The tool was right there. It had been found one step earlier, when the agent stopped to ask for approval. 🫠

I was building a dispatch assistant in pure Dart for a small, made-up field service company (full write-up here). Looking up a work order is free, booking a technician is free, but order_part costs money, so it waits for a person. It took me an evening to find out why the "yes" broke it, and the fix turned into my first PR to Genkit Dart. 🥳

The setup: MCP tools behind an approval

The agent gets its tools from an MCP server and puts toolApproval middleware in front of them. Simplified from my agent:

final mcpTools = await mcpClient.getActiveTools(ai); // includes `work-orders/order_part`

final response = await ai.generate(
  model: model,
  prompt: question,
  tools: mcpTools,
  use: [toolApproval(approved: runWithoutApproval)],
);

if (response.finishReason == FinishReason.interrupted) {
  // Hold the interrupt, show the dispatcher an approve / decline card.
}

runWithoutApproval lists every tool except order_part, so lookups and bookings run straight away.

When the dispatcher approves, I restart the held tool call (held is what I stored when the card was shown):

final resumed = await ai.generate(
  model: model,
  messages: held.messages,
  tools: mcpTools,
  use: [toolApproval(approved: runWithoutApproval)],
  interruptRestart: [held.interrupt.restart({'tool-approved': true})],
);

That second call is the one that failed.

Why the tool vanished only on restart

MCP tools are registered under a namespaced name: work-orders/order_part. But that is not the name the model sees. When Genkit sends tool definitions to the model, toToolDefinition shortens the name to its last segment, order_part, and keeps the full name in metadata.originalName. So the model calls order_part, the name it was given.

Genkit handles that with a second lookup. _resolveTools builds a toolMap keyed by the short name, and _executeTools checks it first:

toolMap['order_part']  →  work-orders/order_part  ✅
registry['order_part'] →  nothing                 ❌

The normal tool loop passes toolMap. The restart path in package:genkit 1.0.1 did not:

// packages/genkit/lib/src/ai/generate.dart, coreGenerate, excerpt (1.0.1)
if (resumeRestart != null) {
  _assertResumable(opts.messages);
  execution = await _executeTools(
    generateRegistry,
    resumeRestart.cast<ToolRequestPart>().toList(),
    c.context,
    cancel: c.cancel,
    middleware: resolvedMiddleware,
  );
}

No toolMap. So _executeTools fell back to a plain registry lookup for order_part, and the registry only knows work-orders/order_part. That is the whole bug.

In practice: a namespaced MCP tool works fine until you put an approval in front of it and restart it. The dispatcher says yes, and nothing gets ordered.

The fix

Resolve the tools on the restart path too, and pass the map along:

// coreGenerate, excerpt (PR #658)
if (resumeRestart != null) {
  _assertResumable(opts.messages);
  final restartTools = await _resolveTools(
    generateRegistry,
    opts.tools,
    resolvedMiddleware,
  );
  execution = await _executeTools(
    restartTools.registry,
    resumeRestart.cast<ToolRequestPart>().toList(),
    c.context,
    cancel: c.cancel,
    middleware: resolvedMiddleware,
    toolMap: restartTools.toolMap,
  );
}

While I was in there I noticed a second, smaller problem in the same block. When a restarted tool's result went back into the history, only output was copied. A tool that returned content (text or image parts) or metadata lost it on restart. The PR now copies both. That part has no test of its own yet.

The test

The regression test needs no API key. A fake model asks for the short name, the namespaced tool interrupts once, and the restart has to find it. A trimmed excerpt (the fake model stores the tool output it receives in observedToolOutput):

genkit.defineTool(
  name: 'work-orders/order_part',
  description: 'Orders a spare part',
  inputSchema: .map(.string(), .dynamicSchema()),
  fn: (input, context) async {
    toolCallCount++;
    if (toolCallCount == 1) return .interrupt('CONFIRM_ORDER');
    return .response('OrderedPart');
  },
);

final response1 = await genkit.generate(
  model: modelRef(modelName), // fake model, calls `order_part`
  prompt: 'order part',
  toolNames: ['work-orders/order_part'],
);
expect(response1.finishReason, FinishReason.interrupted);

final history = [
  Message(role: Role.user, content: [TextPart(text: 'order part')]),
  response1.message!,
];

final response2 = await genkit.generate(
  model: modelRef(modelName),
  messages: history,
  toolNames: ['work-orders/order_part'],
  interruptRestart: [response1.message!.content.first.toolRequestPart!],
);
expect(toolCallCount, 2);
expect(observedToolOutput, 'OrderedPart');

Before the fix, the restart came back as FinishReason.failed with "Tool order_part not found" (the repro in #657). After it, the tool runs a second time and the model gets OrderedPart back. The full test is in packages/genkit/test/ai/interrupt_test.dart in the PR.

Until it ships

The PR is open: genkit-ai/genkit-dart#658, with the repro in #657. The Google CLA check passes; the repo's Dart and Flutter CI are waiting for a maintainer to approve their first run, which GitHub requires for first-time contributors.

Until then, my workaround is a local tool under the bare name that forwards to the MCP one:

final mcpOrderPart = mcpTools.singleWhere((tool) => tool.name.endsWith('/order_part'));
final orderPart = ai.defineTool<PartOrder, String>(
  name: 'order_part',
  description: mcpOrderPart.description ?? 'Orders a spare part for one work order.',
  inputSchema: PartOrder.$schema,
  fn: (input, _) async => .response('${(await mcpOrderPart.call(input.toJson())).output}'),
);
final tools = [...mcpTools.where((tool) => tool != mcpOrderPart), orderPart];

The MCP server still owns the logic, and the adapter goes away once the fix is released.

The lesson I am keeping: test the resume path, not only the happy path. My agent passed every first run. It only broke after somebody said yes. 🙈

Are you using interrupts or approvals in your agents yet? Does your test suite actually cover what happens after the human clicks approve? 👇

Human-in-the-Loop Agents in Pure Dart: Genkit, MCP and an Approval Gate on Cloud Run

Esra Kadah — Tue, 27 Oct 2026 09:53:26 +0000

1. The problem: an agent that can spend money

Most agent demos stop at "the model called a tool and it worked". Real back offices have tools you do not want a model to run on its own.

I built a dispatch assistant for a small, made-up field service company. A dispatcher types "What is the status of WO-1043?" or "Order a 3 kW heating element for WO-1044." and the agent answers. It has three tools:

lookup_work_order reads the site, asset, issue, technician and slot. ✅ Runs on its own.
schedule_visit books a technician for a window. ✅ Runs on its own.
order_part orders a spare part, and that costs money. ❌ Waits for a person.

And I wanted the whole thing in Dart: the agent server, the tool server and the Flutter client, sharing one set of types. No Python sidecar, no Node service in the middle.

2. Architecture: the agent only knows the back office through MCP

Four pieces, all Dart:

The back office as an MCP server (genkit_mcp, Streamable HTTP on loopback). Any MCP client can use it: this agent, an IDE, another agent.
The agent as one Genkit flow (genkit, genkit_google_genai) that connects to that MCP server and gets its tools from it. It never imports the back office directly.
An approval gate (genkit_middleware's toolApproval) in front of every tool that costs money.
The HTTP surface (genkit_shelf): one POST /dispatchAgent plus a health check.

Why MCP for a back office that lives in the same process? Because the boundary is the point. The day the work orders move to a real system, only the MCP server changes. The agent, its prompt and its tests do not.

Exposing the back office is a few lines per tool:

ai.defineTool<PartOrder, String>(
  name: orderPartToolName,
  description:
      'Orders a spare part for one work order, which costs money, and marks the order waiting for parts. '
      'Returns the updated work order as JSON.',
  inputSchema: PartOrder.$schema,
  fn: (input, _) async =>
      .response(describeWorkOrder(workOrders.orderPart(input.orderId, part: input.part), input.orderId)),
);
final server = createMcpServer(ai, McpServerOptions(name: 'work-orders', version: '0.2.0'));
final transport = await StreamableHttpServerTransport.bind(address: InternetAddress.loopbackIPv4, port: port);
await server.start(transport);

Note the tool description says "which costs money". The model reads that too. 😉

3. One schema, three runtimes

The types are schemantic classes in one file with no dart:io import:

@Schema()
abstract class $DispatchAnswer {
  String get answer;

  /// The work order ids the agent looked up to answer, so the client can link them.
  List<String> get orderIds;

  /// Set when the agent stopped before a tool that needs a person's OK; send it back with `approved`.
  String? get approvalId;
}

The same DispatchAnswer is the model's structured output schema, the flow's HTTP response, and the type the Flutter client deserialises through package:genkit/client.dart. Because the file avoids dart:io, the client builds for web, iOS and macOS from the same import. Change a field once, build_runner regenerates, and the compiler tells you everywhere it matters. That is the full-stack Dart pitch in one file. 💙

4. The approval gate: interrupt, hold, restart

toolApproval takes the list of tools that may run without asking. Everything else interrupts generation:

// The MCP client lists `work-orders/<name>`, but the model calls the bare `<name>`; allow both spellings.
final runWithoutApproval = [
  for (final tool in tools)
    if (tool != orderPart) ...[tool.name, bareToolName(tool.name)],
];

final response = await ai.generate(
  model: model,
  messages: messages,
  tools: tools,
  maxTurns: maxAgentTurns,
  outputSchema: DispatchAnswer.$schema,
  use: [toolApproval(approved: runWithoutApproval)],
  interruptRestart: restart,
  interruptRespond: respond,
);

When the model asks for order_part, the response comes back with finishReason == FinishReason.interrupted. The flow stores the conversation so far plus the interrupted tool request under an approvalId and answers the client right away:

{"result": {"answer": "Ordering \"Heating element 3 kW\" for WO-1044 needs your approval.",
            "orderIds": ["WO-1044"], "approvalId": "approval-1"}}

The Flutter client shows Approve and Decline. The next call sends the approvalId back with approved:

return input.approved ?? false
    ? await run(
        messages: held.messages,
        restart: [held.interrupt.restart({'tool-approved': true})],
      )
    : await run(messages: held.messages, respond: [InterruptResponse(held.interrupt, declinedToolOutput)]);

Approve restarts the held call: the tool runs, the model answers from its real result.
Decline never runs the tool. The model gets "Declined by the dispatcher. Nothing was ordered." as the tool output and explains that to the user in its own words.
Each approvalId answers once. It is removed from the pending map on first use, so a double tap cannot order two heating elements. 🙈

Held approvals live in memory. That is a deliberate choice for a demo on Cloud Run with --max-instances 1: one instance, one map. A restart forgets them, and anything beyond a demo wants them in Firestore or a database.

5. The bug: approve, restart… "Tool order_part not found" 🫠

This is where it got interesting. Lookups worked. Bookings worked. The approval prompt appeared. I approved, and the restart failed with Tool order_part not found.

The cause, in Genkit Dart 1.0.1 (packages/genkit/lib/src/ai/generate.dart):

MCP tools are registered under a namespaced name: work-orders/order_part.
The model is shown the short name, order_part, and echoes it back in its tool request.
The normal tool loop resolves that through a short-name map (toolMap), so it finds the tool.
The resume path (interruptRestart) calls the tool executor without that map, falls back to a registry lookup for order_part, misses, and throws.

So any namespaced tool (every MCP tool) works until you put an approval in front of it. I reproduced it with a fake model and two tests, one with a plain tool name and one with work-orders/order_part. Plain passes, namespaced fails. Then I patched a local copy of genkit 1.0.1 through dependency_overrides to pass the map on the restart path, and both tests went green.

It is filed upstream with the repro and the root cause as genkit-ai/genkit-dart#657, and the fix is open as genkit-ai/genkit-dart#658: the restart path now resolves tools the same way the loop does, with a regression test for a namespaced tool. My first open source PR to Genkit Dart. 🥳

Until it is merged and released, the workaround is a local tool under the bare name that forwards to the MCP one:

// Genkit 1.0.1 restarts an approved call by the bare name it sent the model and skips the short-name map
// the normal tool loop uses, so `work-orders/order_part` is never found. A local `order_part` that forwards
// to the MCP tool is.
final orderPart = ai.defineTool<PartOrder, String>(
  name: orderPartToolName,
  description: mcpOrderPart.description ?? 'Orders a spare part for one work order.',
  inputSchema: PartOrder.$schema,
  fn: (input, _) async => .response('${(await mcpOrderPart.call(input.toJson())).output}'),
);
final tools = [...mcpTools.where((tool) => tool != mcpOrderPart), orderPart];

The MCP server stays the single owner of the logic; the adapter is a name and a forward. When #658 ships in a release, it is one deletion.

6. Testing an agent without a key

The agent tests drive the full loop with a fake model defined through ai.defineModel: the fake asks for an MCP tool, the tool answers over real HTTP from the loopback MCP server, and the flow returns the structured answer. They cover a part order that is held, approved, declined, and answered twice.

dart test
00:00 +14: All tests passed!

14 tests, no Gemini call, no API key, no network beyond loopback. That is what makes the approval logic safe to refactor: the expensive, non-deterministic part (the model) is the only thing faked.

7. Shipping: a 21 MB native binary on `scratch`

Dart compiles the server to one native executable, so the runtime image needs no Dart SDK at all:

FROM dart:3.12 AS build
WORKDIR /app
COPY pubspec.yaml pubspec.lock ./
RUN dart pub get
COPY . .
RUN dart pub get --offline && dart compile exe bin/server.dart -o /app/server

FROM scratch
COPY --from=build /runtime/ /
COPY --from=build /app/server /app/server
EXPOSE 8080
ENTRYPOINT ["/app/server"]

The result is 20.7 MB on disk (6 MB compressed content), for an agent server, an MCP server and an HTTP router in one process.

Deploy is one command, with the key from Secret Manager and the service private:

gcloud run deploy genkit-dispatch-agent --source . --region europe-west3 \
  --no-allow-unauthenticated --max-instances 1 --set-secrets GEMINI_API_KEY=gemini-api-key:latest

--no-allow-unauthenticated means only callers with roles/run.invoker get through; everyone else gets a 403. For local development against the private service, gcloud run services proxy serves it on localhost with your own credentials.

One Cloud Run gotcha I had to fix after the first deploy: don't name your health check /healthz. Cloud Run's front end reserves paths ending in z and never forwards them to your container. /health works. 🤌

8. Key findings

A full agent stack in one language works today. Genkit Dart 1.0.1, genkit_mcp, genkit_middleware and genkit_shelf cover flow, tools, MCP client and server, approval and HTTP. The Flutter client shares the types.
Put the approval in the middleware, not in the prompt. A prompt can be talked out of "always ask first". A toolApproval interrupt cannot.
Approvals need ids that answer once. Otherwise a retry or a double tap runs a paid action twice.
MCP plus interrupts is new territory. The first approval I wired up hit a framework bug, a sign that few people have combined them yet. Worth testing the resume path, not only the happy path.
Native Dart on scratch makes Cloud Run cheap and fast to ship: about 21 MB, no runtime to patch.

9. Next steps

Persist pending approvals (Firestore) so they survive instance restarts and allow more than one instance.
Send an identity token from the Flutter client so it can call the private service directly, without the proxy.
Delete the adapter once #658 ships in a Genkit Dart release.

Are you building agents in Dart yet, or still reaching for Python on the server? I would love to hear what your approval story looks like. 👇

Shipping Flutter Web to Firebase When Your GitHub Actions Budget Hits Zero

Esra Kadah — Tue, 27 Oct 2026 08:06:59 +0000

On October 18, right in the middle of shipping a multi-feature audit and a supplement tracker redesign on my personal life_os_app (my daily Flutter Web + Cloud Firestore operating board), GitHub Actions stopped scheduling jobs. The billing meter for my personal account's hosted runner minutes had hit 100%.

Look at what my .github/workflows/ci.yml and deploy-live.yml were doing on every push and pull request:

Spinning up an ubuntu-latest VM.
Pulling the Flutter SDK and warming the Pub cache (~90s).
Installing Python 3 and running 68 CLI sync unit tests (~15s).
Running flutter analyze and 466 widget and accessibility tests (~110s).
Compiling flutter build web --release --no-web-resources-cdn (~140s).
Authenticating via Workload Identity Federation (google-github-actions/auth@v2) and deploying to Firebase Hosting target board (~35s).

That is 6.5 minutes per PR push and another 4 minutes on merge to main. Across 70+ PRs in October, a single-developer personal project burned through thousands of CI minutes doing work my local Apple Silicon MacBook finishes in under 35 seconds.

When your CI budget hits zero on a personal repo, you have two choices: pay for extra runner minutes to compile code your laptop already compiled, or build a deterministic local verification and deployment pipeline that is faster and safer than the YAML workflow it replaces.

Here is the exact architecture I use to keep life_os_app shipping to Firebase Hosting and Cloud Firestore with zero GitHub Actions spend.

Architecture: The Three-Layer Local Verification Gate

Moving deploys to your local machine only works if you never deploy unverified state. In life_os_app, the application state is split across two runtimes:

Python 3.14 CLI Sync Tools (tool/board_*.py): Morning and evening scripts that pull from Apple Reminders, Google Calendar, Harvest, Notion, and GCP Billing, then write structured JSON documents into Cloud Firestore over REST.
Flutter Web Client (lib/): A Riverpod 3 + Material 3 multi-skin web app served from Firebase Hosting with a custom offline Service Worker (web/offline-sw.js).

Layer 1: Firestore Schema Validation Before Every REST Write

One of the biggest risks of running CLI sync tools outside a container is accidentally clobbering fields that the Flutter Web client writes directly from the browser. For example, on the Events and Admin tabs, I tick tasks directly in the UI (config/events.taskTicks and config/admin.done), while tool/board_events.py and tool/board_admin.py sync metadata from Notion and GCP Billing.

To prevent a CLI run from wiping browser taps, tool/board_firestore.py enforces two rules before any HTTP PATCH leaves the machine:

Explicit schema validation on every collection (dayPlans, stats, config, finance, plan).
Field-level update masks (?updateMask.fieldPaths=...) plus hard blocks against overwriting client-owned map keys:

# tool/board_firestore.py
if path == "config/events" and "taskTicks" in data and not fields:
    raise SystemExit(
        "refusing to overwrite config/events.taskTicks without --fields; "
        "pass --fields updated,source,events"
    )
if path == "config/admin" and "done" in data and not fields:
    raise SystemExit(
        "refusing to overwrite config/admin.done without --fields"
    )

In addition, caching the gcloud auth print-access-token call with @functools.lru_cache(maxsize=1) and enforcing a 15-second socket timeout cut multi-document Firestore sync latency by 80% and eliminated hanging background processes when switching Wi-Fi networks.

Layer 2: Per-Document Decode Isolation in Flutter Streams

In Cloud Firestore, a single malformed field inside one historical document in a collection query (collection('dayPlans').snapshots()) will normally throw a FormatException or TypeError inside .map(), killing the entire StreamProvider and replacing your UI with an error state.

During my audit pass, I hardened every repository to isolate decoding per document:

// lib/features/day_board/data/board_repository.dart
List<T> _decodeEach<T>(
  QuerySnapshot<JsonMap> query,
  T Function(JsonMap data, String id) decode,
) {
  final results = <T>[];
  for (final doc in query.docs) {
    try {
      results.add(decode(doc.data(), doc.id));
    } on Object catch (error, stackTrace) {
      developer.log(
        'Skipping malformed document ${doc.reference.path}',
        name: 'day_board.repository',
        error: error,
        stackTrace: stackTrace,
      );
    }
  }
  return results;
}

When saving multi-day edits (such as editing 7 days of focus blocks and habit notes in the This Week sheet), replacing 14 sequential await set() calls with a single atomic WriteBatch (saveWeekEditsBatch) eliminated partial-save race conditions on flaky mobile connections.

Layer 3: Self-Contained Web Bundles (`--no-web-resources-cdn`) & Service Worker Cleanup

When deploying Flutter Web to Firebase Hosting for daily use on iPhone, iPad, and desktop, CDN font/CanvasKit fetches can stall on airplane or train Wi-Fi. Building with --no-web-resources-cdn bundles CanvasKit and font assets directly into build/web/, paired with a custom web/offline-sw.js that races network against a 3.5-second timeout before falling back to cache:

// web/offline-sw.js
function networkFirst(request, timeoutMs) {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
    fetch(request)
      .then((response) => {
        if (response && response.ok) {
          caches.open(CACHE).then((cache) => cache.put(request, response.clone()));
        }
        resolve(response);
      })
      .catch(reject)
      .finally(() => clearTimeout(timer));
  }).catch(() => caches.match(request));
}

Notice the .finally(() => clearTimeout(timer)) cleanup: without it, every fast network response leaves an orphan timer running until timeoutMs expires.

Benchmarking: Cloud CI vs. Local Verification Gate

Stage	GitHub Actions (`ubuntu-latest`)	Local Apple Silicon Gate	Improvement
Python CLI Unit Tests (`68 tests`)	14.2s (with setup)	0.02s	710x faster
Dart Format + Analyze + `466 Flutter tests`	118.0s	14.5s	8.1x faster
`flutter build web --release --no-web-resources-cdn`	142.0s	14.8s	9.6x faster
`firebase deploy --only hosting:board`	34.0s	3.1s	11.0x faster
Total Wall-Clock Time	~5m 08s (plus SDK cache)	~32.4s	~9.5x faster, $0 CI cost

Table totals exclude the Flutter SDK download and Pub cache warm-up (~90s), which is what brings a full PR run to ~6.5 minutes.

Key Takeaways for Flutter & Firebase Engineers

Keep CI YAML for PRs when budget allows, but make your local gate identical. A single local command (dart format -l 120 lib/ test/ && flutter analyze && python3 -m unittest discover -s tool -p '*_test.py' && flutter test) guarantees parity before firebase deploy.
Use Firebase Hosting multi-site targets (hosting:board, hosting:board-staging). Mapping targets in .firebaserc lets you preview on staging or promote to live with --only hosting:board without touching sibling sites on the same GCP project.
Never let one bad Firestore document take down a collection stream. Wrap per-document .fromJson() calls inside a helper that logs to dart:developer and skips the corrupted record.
Test accessibility contrast and 44pt tap targets in flutter test, not in production. Running textContrastGuideline and androidTapTargetGuideline with GoogleFonts.config.allowRuntimeFetching = false catches neon text shadow contrast drops and 32pt icons in milliseconds.

The complete local release gate in one command:

dart format -l 120 lib/ test/ && \
  flutter analyze && \
  python3 -m unittest discover -s tool -p '*_test.py' && \
  flutter test && \
  flutter build web --release --no-web-resources-cdn && \
  firebase deploy --only hosting:board --project esra-life-os