basic-tool-interrupts-exp

Documentation

Overview

This sample is basic-tool-interrupts, written against the in-preview tools API in genkit/exp. It is slated to replace the one basic-tool-interrupts uses in the next major version, so the two are worth reading side by side: same human in the loop (HITL) approval, same flow, and the differences are all API.

A tool interrupt is how Genkit does HITL: transferMoney pauses generation when a transfer is large enough to need approving, and the flow runs a second turn that resumes the tool with the answer.

DefineInterruptibleTool takes a third type parameter for what comes back on the resume, which is what the differences all follow from:

• The tool function takes a plain context.Context and an *Approval, rather than *ai.ToolContext. The parameter is nil on the first call and set on the resume, so the tool reads a typed value instead of asking whether it was resumed and then pulling metadata out by key.
• tool.Interrupt pauses with a typed value, in place of ai.InterruptWith.
• Tool.Resume carries a typed Approval, in place of RestartWith and an ai.WithResumedMetadata map.

The approve field stands in for the person: a real app would hand the pending interrupt to a client and run the second turn when they answer.

Run it:

go run .

Or with the Dev UI, to call the flow from a browser and read a trace of both turns at http://localhost:4000/traces:

curl -sL cli.genkit.dev | bash    # install the Genkit CLI, once
genkit start -- go run .

Or over HTTP. The balance carries across requests, so run these in order. Decline a transfer that needs approving, which leaves the money where it is:

curl -N -X POST 'http://localhost:8080/transferFlow?stream=true' \
  -H "Content-Type: application/json" \
  -d '{"data": {"request": "Send $120 to bob", "approve": false}}'

Then approve the same one, which spends it:

curl -N -X POST 'http://localhost:8080/transferFlow?stream=true' \
  -H "Content-Type: application/json" \
  -d '{"data": {"request": "Send $120 to bob", "approve": true}}'

A small transfer needs no approval, so it finishes in one turn:

curl -N -X POST 'http://localhost:8080/transferFlow?stream=true' \
  -H "Content-Type: application/json" \
  -d '{"data": {"request": "Send $20 to alice", "approve": false}}'

Repeating the $120 one now asks for more than is left, which the tool answers outright rather than pausing on.