feat(js/ai): added a simple way to interrupt tool execution

[pavelgj]

ai.defineTool(
  { name: 'testTool', description: 'description' },
  async () => {
    if (anyReason) {
      interruptTool()
    }
    return doToolThings();
  }
);

[mbleigh]

I'd like this to be able to take an argument of Record<string, any> and whatever gets passed to that gets annotated onto the toolRequest it's associated with.

const transferMoney = ai.defineTool({
  inputSchema: z.object({amount: z.number(), fromAccount: z.string(), toAccount: z.string()}),
  outputSchema: z.object({balance: z.number()}),
}, ({amount, fromAccount, toAccount}, {interrupt, context}) {
  if (amount > 1000) interrupt({confirm: "The requested amount is large, please confirm all the details carefully."});
  if (!getUserAccounts(context.auth.uid).includes(toAccount)) interrupt({confirm: `The account '${toAccount}' does not belong to you. Please confirm you wish to transfer money to an account owned by someone else.`;
  return doMoneyTransfer(fromAccount,toAccount,amount);
});

Results in:

{role: "model", content: [..., {toolRequest: {name: "transferMoney", input: {amount: 5000, ...}, metadata: {interrupt: {confirm: "..."}}}}]}

This will allow the developer to customize and control how interrupts happen and also lay foundation for higher-level interrupt primitives down the road.

[mbleigh]

And maybe metadata: {interrupt: true} if no argument provided

[pavelgj]

this implies this interrupt is resumable/rerunnable where the interrupt won't be triggered? Like we we had with durable flows? How do you imagine the user facing api for this?

[mbleigh]

What do you think about adding interrupt as an item in the second argument of the tool instead?

ai.defineTool(..., (input, {context, interrupt}) => {
  interrupt();
});

[mbleigh]

It's up to the dev to figure it what to do with the metadata, for now it's just an annotation and the dev can use it to drive UI etc. I want there to be a mechanism/API to explicitly signal (maybe via context?) that it's a resumed interruption, but I think we can figure that out later.

…

On Wed, Jan 22, 2025, 5:44 PM Pavel Jbanov ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In js/ai/src/tool.ts <#1583 (comment)>: > +export function interruptTool() { + throw new ToolInterruptError(); +} this implies this interrupt is resumable/rerunnable where the interrupt won't be triggered? Like we we had with durable flows? How do you imagine the user facing api for this? — Reply to this email directly, view it on GitHub <#1583 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAAH7U7LAPMI56VPE67AFL2MBCPNAVCNFSM6AAAAABUTITF3CVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDKNRYGY4DCNZZGE> . You are receiving this because you commented.Message ID: ***@***.***>