You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 988fd1a
Browse filesBrowse the repository at this point in the historyBrowse files
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
Copy file name to clipboardExpand all lines: docs/guides/tools/node_tool/index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -70,7 +70,7 @@ For workflows, the input schema is specified using `input_schema` on the `Workfl
70
70
71
71
### Function node as a tool
72
72
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.
Copy file name to clipboardExpand all lines: docs/guides/workflow/base_node/index.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -50,7 +50,7 @@ The nine options exist on every node, but the way you set one depends on how the
50
50
51
51
| How you build the node | What you can pass |
52
52
| :--- | :--- |
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`|
54
54
|`FunctionNode(func=...)`| the same, minus the parallel-worker flags, plus `state_schema`|
55
55
|`Workflow(...)`, `JoinNode(...)`, a `Node` subclass, `Agent(...)`| all nine, as ordinary keyword arguments |
Copy file name to clipboardExpand all lines: docs/guides/workflow/function_node/index.md
+27-4Lines changed: 27 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -98,18 +98,20 @@ rest of the workflow sees it:
98
98
99
99
## Configuration options
100
100
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:
104
105
105
106
| Option | Type | Default | Description |
106
107
| :--- | :--- | :--- | :--- |
107
108
|`parameter_binding`|`'state' \| 'node_input'`|`'state'`| Where non-context parameters are looked up. |
108
109
|`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`. |
110
111
|`retry_config`|`RetryConfig \| None`|`None`| Retry policy. See [RetryConfig](../retry_config/index.md). |
111
112
|`timeout`|`float \| None`|`None`| Seconds before the node is canceled and fails with `NodeTimeoutError`. |
112
113
|`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`. |
113
115
|`state_schema`|`type[BaseModel] \| None`|`None`| Declares the state keys the node may write. `FunctionNode(...)` only; `@node` does not take it. |
114
116
115
117
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
129
131
also infers `input_schema` and `output_schema` from the whole signature, which
130
132
is what makes a function node usable as an agent's tool.
131
133
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)
Copy file name to clipboardExpand all lines: docs/guides/workflow/node/index.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ The `@node` decorator and `node()` function wrap Python functions, agents, tools
6
6
7
7
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:
8
8
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.
10
10
-**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.
11
11
-**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.
12
12
@@ -89,6 +89,7 @@ When `parallel_worker` is `False`, calling the node runs your `run_node_impl` as
89
89
|`parallel_worker`|`bool`|`False`| Runs the node concurrently across each item of an input list. See [parallel worker mode](../parallel_worker/index.md). |
90
90
|`max_parallel_workers`|`int \| None`|`None`| Maximum number of list items processed at once when `parallel_worker=True`. `None` places no cap on concurrency. |
91
91
|`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. |
92
93
|`parameter_binding`|`'state' \| 'node_input'`|`'state'`| How a wrapped function resolves parameters other than `ctx` and `node_input`. |
93
94
94
95
### `name`
@@ -97,7 +98,7 @@ Every distinct node in a workflow must have a unique name that is a valid Python
97
98
98
99
### `rerun_on_resume`
99
100
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.
101
102
102
103
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.
103
104
@@ -237,8 +238,8 @@ Because `PrefixNode` inherits from `Node` rather than `BaseNode`, passing `paral
237
238
238
239
Keep the following constraints in mind when wrapping nodes with `node()` or subclassing `Node`:
239
240
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`.
242
243
-**`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})`.
243
244
-**`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`.
0 commit comments