Skip to content

Commit 988fd1a

Browse files
DeanChensjcopybara-github
authored andcommitted
feat(workflow): support require_confirmation in @node and FunctionNode
Add support for `require_confirmation` (boolean or callable predicate) on `@node`, `node()`, `build_node()`, and `FunctionNode`, aligning node confirmation semantics with `FunctionTool` and `_ToolNode`: - Automatically default `rerun_on_resume=True` in `@node`, `node()`, and `build_node()` when `require_confirmation` is configured, and require `rerun_on_resume=True` on `FunctionNode` (raising `WorkflowConfigurationError` if `rerun_on_resume=False`). - Gate function execution inside `FunctionNode._run_impl` via `RequestInput` (`wf_tool_confirmation:{node_path}` with `ToolConfirmation` schema), executing once upon approval or skipping the function and emitting `{"error": "This tool call is rejected."}` upon rejection. Co-authored-by: Shangjie Chen <[email protected]> PiperOrigin-RevId: 998032598
1 parent 5ee5cf8 commit 988fd1a

11 files changed

Lines changed: 929 additions & 97 deletions

File tree

‎.agents/skills/adk-agent-builder/references/function-nodes.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,8 @@ worker = node(some_func, parallel_worker=True)
152152
```
153153

154154
Accepted keywords: `name`, `rerun_on_resume`, `retry_config`, `timeout`,
155-
`parallel_worker`, `max_parallel_workers`, `auth_config`, `parameter_binding`.
155+
`parallel_worker`, `max_parallel_workers`, `auth_config`,
156+
`require_confirmation`, `parameter_binding`.
156157

157158
## Routing and state from a node
158159

@@ -166,6 +167,25 @@ def update_counter(node_input: str):
166167
return Event(output=node_input, state={'last_input': node_input})
167168
```
168169

170+
## Requiring confirmation before a node runs
171+
172+
`require_confirmation` pauses the workflow with an `adk_request_input`
173+
interrupt (`wf_tool_confirmation:{node_path}`) before the function runs. It
174+
accepts a `bool` or a sync/async predicate callable receiving the function's
175+
bound arguments (plus `ctx` or `node_input` if declared). `@node` automatically
176+
defaults `rerun_on_resume=True` when `require_confirmation` is set.
177+
178+
```python
179+
@node(require_confirmation=True)
180+
def delete_file(path: str) -> str:
181+
return f'Deleted {path}'
182+
183+
184+
@node(require_confirmation=lambda amount: amount > 1000)
185+
def transfer_funds(amount: int) -> str:
186+
return f'Transferred {amount}'
187+
```
188+
169189
## Requiring authentication before a node runs
170190

171191
`auth_config` makes the framework request user credentials before the node's

‎docs/guides/tools/node_tool/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ For workflows, the input schema is specified using `input_schema` on the `Workfl
7070

7171
### Function node as a tool
7272

73-
Plain functions and generators passed to an agent's `tools` list are wrapped as [`FunctionTool`](../function_tool/index.md) instances, which already support streaming intermediate `Event` objects and pausing with `RequestInput`. Decorating a function with `@node` wraps it as a `FunctionNode` instead, which is useful when you want node-level execution settings such as `retry_config`, `timeout`, or `auth_config`, or when you share the same node with a `Workflow` graph. Tool parameter names and types are inferred directly from the function signature and docstrings.
73+
Plain functions and generators passed to an agent's `tools` list are wrapped as [`FunctionTool`](../function_tool/index.md) instances, which already support streaming intermediate `Event` objects and pausing with `RequestInput`. Decorating a function with `@node` wraps it as a `FunctionNode` instead, which is useful when you want node-level execution settings such as `retry_config`, `timeout`, `auth_config`, or `require_confirmation`, or when you share the same node with a `Workflow` graph. Tool parameter names and types are inferred directly from the function signature and docstrings.
7474

7575
```python
7676
from google.adk import Agent

‎docs/guides/workflow/base_node/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ The nine options exist on every node, but the way you set one depends on how the
5050

5151
| How you build the node | What you can pass |
5252
| :--- | :--- |
53-
| `@node(...)` on a function | `name`, `rerun_on_resume`, `retry_config`, `timeout`, plus `auth_config`, `parameter_binding`, `parallel_worker`, `max_parallel_workers` |
53+
| `@node(...)` on a function | `name`, `rerun_on_resume`, `retry_config`, `timeout`, plus `auth_config`, `require_confirmation`, `parameter_binding`, `parallel_worker`, `max_parallel_workers` |
5454
| `FunctionNode(func=...)` | the same, minus the parallel-worker flags, plus `state_schema` |
5555
| `Workflow(...)`, `JoinNode(...)`, a `Node` subclass, `Agent(...)` | all nine, as ordinary keyword arguments |
5656

‎docs/guides/workflow/function_node/index.md‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,18 +98,20 @@ rest of the workflow sees it:
9898

9999
## Configuration options
100100

101-
`FunctionNode` introduces one option of its own, `parameter_binding`, and the
102-
rest come from `BaseNode`. Neither `@node` nor the `FunctionNode` constructor
103-
accepts every `BaseNode` field, though, so only these are available:
101+
`FunctionNode` introduces two options of its own, `parameter_binding` and
102+
`require_confirmation`, and the rest come from `BaseNode`. Neither `@node` nor
103+
the `FunctionNode` constructor accepts every `BaseNode` field, though, so only
104+
these are available:
104105

105106
| Option | Type | Default | Description |
106107
| :--- | :--- | :--- | :--- |
107108
| `parameter_binding` | `'state' \| 'node_input'` | `'state'` | Where non-context parameters are looked up. |
108109
| `name` | `str \| None` | `None` | Node name. Falls back to the function's `__name__`. |
109-
| `rerun_on_resume` | `bool` | `False` | Whether the node reruns after an interrupt, or completes with the resuming input. |
110+
| `rerun_on_resume` | `bool` | `False` | Whether the node reruns after an interrupt, or completes with the resuming input. Nodes with `require_confirmation` or `auth_config` require `True`. |
110111
| `retry_config` | `RetryConfig \| None` | `None` | Retry policy. See [RetryConfig](../retry_config/index.md). |
111112
| `timeout` | `float \| None` | `None` | Seconds before the node is canceled and fails with `NodeTimeoutError`. |
112113
| `auth_config` | `AuthConfig \| None` | `None` | Requests user authentication before the node runs. |
114+
| `require_confirmation` | `bool \| Callable[..., bool]` | `False` | Gates execution on user approval, either unconditionally or when the predicate callable returns `True`. Requires `rerun_on_resume=True`. |
113115
| `state_schema` | `type[BaseModel] \| None` | `None` | Declares the state keys the node may write. `FunctionNode(...)` only; `@node` does not take it. |
114116

115117
Two options are the other way round. `@node` also takes `parallel_worker` and
@@ -129,6 +131,27 @@ Pydantic model), and its keys are matched to parameter names instead. That mode
129131
also infers `input_schema` and `output_schema` from the whole signature, which
130132
is what makes a function node usable as an agent's tool.
131133

134+
### `require_confirmation`
135+
136+
Setting `require_confirmation=True` pauses the workflow with an
137+
`adk_request_input` interrupt (`wf_tool_confirmation:{node_path}`) before the
138+
function body runs. You can also pass a sync or async callable predicate that
139+
receives the function's bound arguments (and `ctx` or `node_input` if declared)
140+
and returns a `bool`:
141+
142+
```python
143+
from google.adk.workflow import node
144+
145+
@node(require_confirmation=lambda amount: amount > 1000)
146+
def transfer_funds(amount: int) -> str:
147+
return f"Transferred ${amount}"
148+
```
149+
150+
When resumed with `{"confirmed": True}`, the function executes once with the
151+
parsed `ToolConfirmation` available on `ctx.tool_confirmation`. When resumed
152+
with `{"confirmed": False}`, the function body is skipped and the node emits
153+
`{"error": "This tool call is rejected."}` as its output.
154+
132155
### `input_schema` and `output_schema` are inferred, not passed
133156

134157
Neither `@node` nor `FunctionNode(...)` accepts `input_schema`,

‎docs/guides/workflow/node/index.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The `@node` decorator and `node()` function wrap Python functions, agents, tools
66

77
A workflow graph accepts functions, agents, tools, and other workflows directly in its edges, wrapping each one with default settings as the graph is built. You reach for `node` or `Node` when those defaults are not enough:
88

9-
- **Configuring a function at definition time**: `@node(...)` attaches settings such as `timeout`, `retry_config`, `rerun_on_resume`, `parameter_binding`, and `parallel_worker` directly to a Python function.
9+
- **Configuring a function at definition time**: `@node(...)` attaches settings such as `timeout`, `retry_config`, `rerun_on_resume`, `require_confirmation`, `parameter_binding`, and `parallel_worker` directly to a Python function.
1010
- **Overriding settings or reusing a step across a graph**: Calling `node(step, name=..., timeout=...)` on an existing function, `Agent`, `BaseTool`, or `BaseNode` returns a configured copy, leaving the original untouched so it can be reused elsewhere in the same graph or in other workflows.
1111
- **Writing a reusable node class**: Subclassing `Node` and implementing `run_node_impl` gives your custom node class all [`BaseNode`](../base_node/index.md) settings plus [`parallel_worker`](../parallel_worker/index.md) support out of the box.
1212

@@ -89,6 +89,7 @@ When `parallel_worker` is `False`, calling the node runs your `run_node_impl` as
8989
| `parallel_worker` | `bool` | `False` | Runs the node concurrently across each item of an input list. See [parallel worker mode](../parallel_worker/index.md). |
9090
| `max_parallel_workers` | `int \| None` | `None` | Maximum number of list items processed at once when `parallel_worker=True`. `None` places no cap on concurrency. |
9191
| `auth_config` | `AuthConfig \| None` | `None` | Requests user credentials before the function runs. Applies to callables and requires `rerun_on_resume=True`. |
92+
| `require_confirmation` | `bool \| Callable[..., bool] \| None` | `None` | Gates execution on user approval before the function runs, either unconditionally or when the predicate callable returns `True`. Automatically enables `rerun_on_resume=True` when not explicitly set. |
9293
| `parameter_binding` | `'state' \| 'node_input'` | `'state'` | How a wrapped function resolves parameters other than `ctx` and `node_input`. |
9394

9495
### `name`
@@ -97,7 +98,7 @@ Every distinct node in a workflow must have a unique name that is a valid Python
9798

9899
### `rerun_on_resume`
99100

100-
Controls how the node behaves when a workflow resumes after pausing for human input or tool confirmation. Functions default to `False`, meaning the resuming input becomes the node's output without running the function body again. Setting `rerun_on_resume=True` re-executes the function from the start on resume, which is required whenever the node calls `ctx.run_node()`, yields a `RequestInput` and inspects `ctx.resume_inputs`, or uses `auth_config`.
101+
Controls how the node behaves when a workflow resumes after pausing for human input or tool confirmation. Functions default to `False`, meaning the resuming input becomes the node's output without running the function body again. Setting `rerun_on_resume=True` re-executes the function from the start on resume, which is required whenever the node calls `ctx.run_node()`, yields a `RequestInput` and inspects `ctx.resume_inputs`, or uses `auth_config`. When `require_confirmation` is set, `rerun_on_resume` defaults to `True` automatically.
101102

102103
When `parallel_worker=True`, `rerun_on_resume` is forced to `True` automatically so the worker can re-collect completed item outputs from the event log on resume.
103104

@@ -237,8 +238,8 @@ Because `PrefixNode` inherits from `Node` rather than `BaseNode`, passing `paral
237238

238239
Keep the following constraints in mind when wrapping nodes with `node()` or subclassing `Node`:
239240

240-
- **`node(existing_node)` without overrides does not copy the node.** When you pass a `BaseNode` to `node()` without setting `name`, `rerun_on_resume`, `retry_config`, `timeout`, or `parallel_worker=True`, `node()` returns the exact same instance. To use the same node at two places in one graph, you must pass a distinct `name` so a new copy is created and the two steps do not collide.
241-
- **`auth_config` and `parameter_binding` do not apply when wrapping an existing `BaseNode`, `BaseAgent`, or `BaseTool`.** Those two options are only consumed when `node()` wraps a plain Python callable into a `FunctionNode`. Passing them alongside an already-constructed `FunctionNode` or `Agent` has no effect.
241+
- **`node(existing_node)` without overrides does not copy the node.** When you pass a `BaseNode` to `node()` without setting `name`, `rerun_on_resume`, `retry_config`, `timeout`, `require_confirmation`, or `parallel_worker=True`, `node()` returns the exact same instance. To use the same node at two places in one graph, you must pass a distinct `name` so a new copy is created and the two steps do not collide.
242+
- **`auth_config`, `require_confirmation`, and `parameter_binding` only apply to function nodes.** `auth_config` and `parameter_binding` are only consumed when `node()` wraps a plain Python callable into a `FunctionNode`. `require_confirmation` applies to callables and existing `FunctionNode` instances (including a `NodeTool` wrapping a `FunctionNode`); passing `require_confirmation` when wrapping another `BaseNode` or `BaseTool` raises `WorkflowConfigurationError`.
242243
- **`parallel_worker` and `max_parallel_workers` are frozen on `Node` instances.** Both fields are declared with `frozen=True`, so mutating `my_node.parallel_worker = True` after construction raises a Pydantic validation error. Pass them to the constructor or to `node()`, or create a new instance with `model_copy(update={"parallel_worker": True})`.
243244
- **`run_node_impl` must be an async generator.** Even if your `Node` subclass emits only a single value, `run_node_impl` must be defined with `async def` and `yield` its output rather than using `return`. A `Node` subclass also receives raw `node_input` without automatic `types.Content`-to-`str` conversion unless you set `input_schema`.
244245

0 commit comments

Comments
 (0)