Skip to content

feat(py): respond/restart improvements#5004

Draft
huangjeff5 wants to merge 8 commits intomainfrom
jh-interrupts
Draft

feat(py): respond/restart improvements#5004
huangjeff5 wants to merge 8 commits intomainfrom
jh-interrupts

Conversation

@huangjeff5
Copy link
Copy Markdown
Contributor

@huangjeff5 huangjeff5 commented Mar 26, 2026

Adds restart support in the Python SDK and other improvements.

Tools (or wrapped tools) can raise Interrupt, which stops the current generation turn and surfaces the pending ToolRequestPart with interrupt metadata.

Now, The execution flow is paused, giving the caller the option to either respond, and restart the tool execution with replaced input and resumed metadata.

See samples for update usage.

Core Changes

  • Moved interrupt helper off of ToolRunContext. Now you raise Interrupt to trigger interruptions.
  • Added define_interrupt primitive, which provides the default Interrupt tool, with the option to provide a input schema to constrain the model call.
  • Renamed tool_response helper to respond_to_interrupt, and added restart_interrupted_tool to support the restart use case.
  • In the restart use case, use ContextVars to store _resumed_metadata and _replaced_input and propagate those to the tool inside tool_fn_wrapper.
  • Resume options were flattened and added directly onto the generate() signature.

Related Changes

  • You can pass tools directly inline (as opposed to requiring a str). tools signature now accepts str, Action, or Callable.
    • Flattened prompt signature so that there isn't a separate opts argument; those PromptGenerationOptions are flat kwargs now.
  • I ran into 4xx issues with Gemini when sending tools with scalar inputs. To solve this, I have the genai plugin convert the input schema into an object with 'value' key. And in the core framework, when handling this, we handle this special case and unwrap it.
  • Tools were running sequentially, not in parallel. This PR fixes that.

@github-actions github-actions bot added docs Improvements or additions to documentation python Python config labels Mar 26, 2026
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a significant refactor of the tool interrupt and resume mechanism within the Genkit Python SDK. Key changes include replacing the generic tool_responses parameter with more explicit resume_respond, resume_restart, and resume_metadata options in the generate and prompt execution APIs. A new Interrupt exception has been added for tools to signal pauses, complemented by helper functions like respond_to_interrupt and restart_interrupted_tool for resuming execution. Additionally, the ExecutablePrompt API was updated to accept configuration options as keyword arguments rather than a single opts dictionary. The Google AI plugin was also updated to handle scalar tool inputs for Gemini and to correctly report the finish_reason in streaming responses. I have no feedback to provide as there are no review comments to assess.

metadata: dict[str, object] | None = None,
span_metadata: dict[str, SpanAttributeValue] | None = None,
*,
output_schema: type[BaseModel] | dict[str, object] | None = None,
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only allow input_schema override, not output_schema (?)

import tempfile
from pathlib import Path
from typing import Any
from typing import Any, cast
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is cast used in this file?

metadata: dict[str, object] | None = None,
span_metadata: dict[str, SpanAttributeValue] | None = None,
*,
output_schema: type[BaseModel] | dict[str, object] | None = None,
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not sure why this was added

ai, *_ = setup_test()

my_prompt = ai.define_prompt(**prompt)
my_prompt = ai.define_prompt(
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

avoid manual construction

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

config docs Improvements or additions to documentation python Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants