tool method

Future<ToolResult> tool(ToolRequestPart request, ActionFnArg<void, dynamic, void> ctx, Future<ToolResult> next(ToolRequestPart request, ActionFnArg<void, dynamic, void> ctx))

Middleware for tool execution.

Wraps each tool call. Input is dynamic because tools can have varied input schemas.

Works with the same ToolResult a tool function returns: return .response(output) to answer the model, or .interrupt(data) to stop the generate loop and hand the tool request back to the caller (human-in-the-loop). The generate loop turns the final result into the tool response message (filling in the request's ref and name), so middleware never builds one by hand.

A middleware that post-processes responses must pass interrupts through:

final result = await next(request, ctx);
return switch (result) {
  ToolResponseResult(:final output, :final parts, :final metadata) =>
    .response(redact(output), parts: parts, metadata: metadata),
  ToolInterruptResult() => result,
};

Implementation

Future<ToolResult> tool(
  ToolRequestPart request,
  ActionFnArg<void, dynamic, void> ctx,
  Future<ToolResult> Function(
    ToolRequestPart request,
    ActionFnArg<void, dynamic, void> ctx,
  )
  next,
) {
  return next(request, ctx);
}