feat(go): improved tool interrupts API to be more ergonomic

[apascal07]

This PR introduces a new strongly-typed API for tool interrupts in Genkit Go, enabling human-in-the-loop workflows with better type safety and ergonomics.

New APIs

Triggering Interrupts

ai.InterruptWith[T](ctx, meta) - Interrupt tool execution with typed metadata:

return TransferOutput{}, ai.InterruptWith(ctx, TransferInterrupt{
    Reason:  "confirm_large",
    Amount:  input.Amount,
})

Handling Interrupts

ai.InterruptAs[T](part) - Extract typed metadata from an interrupt:

if meta, ok := ai.InterruptAs[TransferInterrupt](interrupt); ok {
    switch meta.Reason {
    case "confirm_large":
        // handle confirmation
    }
}

Resuming Interrupted Tools

Given a tool defined as:

myTool := genkit.DefineTool[TransferInput, TransferOutput](...)

ai.ToolDef[In, Out].RestartWith(part, opts...) - Re-execute tool with optional modifications:

// Simple restart (re-run with same input)
part, err := myTool.RestartWith(interrupt)

// Restart with replaced input (must be TransferInput)
part, err := myTool.RestartWith(interrupt, ai.WithNewInput(TransferInput{Amount: adjustedAmount}))

ai.ToolDef[In, Out].RespondWith(part, output, opts...) - Provide output directly without re-running:

// Output must be TransferOutput
part, err := myTool.RespondWith(interrupt, TransferOutput{Status: "cancelled", Message: "User declined"})

Tool Context Helpers

ai.ToolContext.IsResumed() - Check if tool is being restarted after interrupt:

if !ctx.IsResumed() && input.Amount > 100 {
    return TransferOutput{}, ai.InterruptWith(ctx, ...)
}

ai.OriginalInputAs[T](ctx) - Access original input when WithNewInput was used:

if orig, ok := ai.OriginalInputAs[TransferInput](ctx); ok {
    message = fmt.Sprintf("Adjusted from $%.2f", orig.Amount)
}

Deprecated APIs

Deprecated	Replacement
tool.Respond(part, output, opts)	tool.RespondWith(part, output, opts...)
tool.Restart(part, opts)	tool.RestartWith(part, opts...)

Key Improvements

1. Type Safety: Generic functions ensure interrupt metadata and tool inputs/outputs are properly typed at compile time
2. Error Handling: New RestartWith/RespondWith return errors instead of silently returning nil on invalid input
3. Validation: Tool name validation prevents accidentally using the wrong tool to respond to an interrupt
4. Functional Options: WithNewInput[In] and WithResumedMetadata[In] provide a cleaner API than struct-based options

Sample

See samples/intermediate-interrupts/ for a complete example demonstrating a payment agent with:

• Insufficient balance handling (offers adjusted amount via WithNewInput)
• Large transfer confirmation (simple restart after approval)
• Cancellation (direct response via RespondWith)

Checklist (if applicable):

• PR title is following https://www.conventionalcommits.org/en/v1.0.0/
• Tested (manually, unit tested, etc.)
• Docs updated: Updated tool interrupt docs for Go to reflect new APIs. genkit-ai/docsite#205

[gemini-code-assist]

Summary of Changes

Hello @apascal07, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request focuses on refining the Go API for tool interrupts, making it more intuitive and robust for developers. It introduces a generic tool definition, provides type-safe utilities for managing tool execution flow after interruptions, and standardizes internal data conversions. These changes aim to streamline the development of applications that require interactive or conditional tool execution within generative AI workflows.

Highlights

• Improved Tool Interrupts API: The Go API for handling tool interrupts has been significantly refactored to be more ergonomic and type-safe. This includes moving interrupt-related functions to methods on ToolContext and introducing new functional options for RespondWith and RestartWith.
• Generic ToolDef Type: The tool struct has been replaced with a generic ToolDef[In, Out any] type, enhancing type safety and clarity for tool definitions and interactions.
• New Helper Functions for ToolContext: Several new helper methods have been added to ToolContext, such as InterruptWith, InterruptAs, IsResumed, ResumedValue, and OriginalInputAs, to simplify common patterns when dealing with tool interruptions and resumptions.
• Standardized JSON Conversions: New generic utility functions MapToStruct and StructToMap have been introduced in go/internal/base/json.go to standardize JSON conversions, replacing custom implementations in various plugins.
• Enhanced Model Referencing: Model referencing in Google Gen AI plugins and samples has been updated to use full model names (e.g., googleai/gemini-2.5-flash) for consistency.
• New Tool Interrupts Sample: A new sample (go/samples/intermediate-interrupts/main.go) has been added to demonstrate the practical application of the improved tool interrupts API, showcasing human-in-the-loop interactions for a payment agent.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed improvement to the tool interrupts API, making it more ergonomic and type-safe. The changes include a major refactoring of the tool definition, the addition of several convenient helper functions, comprehensive new tests, and a new sample to demonstrate the feature. Overall, the code quality is high. I've identified a couple of minor issues related to API design that could lead to inconsistencies or potential runtime errors, and I've provided suggestions to address them.