1  ---
  2  title: "Human-in-the-Loop"
  3  id: human-in-the-loop-api
  4  description: "Abstractions for integrating human feedback and interaction into Agent workflows."
  5  slug: "/human-in-the-loop-api"
  6  ---
  7  
  8  
  9  ## dataclasses
 10  
 11  ### ConfirmationUIResult
 12  
 13  Result of the confirmation UI interaction.
 14  
 15  **Parameters:**
 16  
 17  - **action** (<code>str</code>) – The action taken by the user such as "confirm", "reject", or "modify".
 18    This action type is not enforced to allow for custom actions to be implemented.
 19  - **feedback** (<code>str | None</code>) – Optional feedback message from the user. For example, if the user rejects the tool execution,
 20    they might provide a reason for the rejection.
 21  - **new_tool_params** (<code>dict\[str, Any\] | None</code>) – Optional set of new parameters for the tool. For example, if the user chooses to modify the tool parameters,
 22    they can provide a new set of parameters here.
 23  
 24  ### ToolExecutionDecision
 25  
 26  Decision made regarding tool execution.
 27  
 28  **Parameters:**
 29  
 30  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
 31  - **execute** (<code>bool</code>) – A boolean indicating whether to execute the tool with the provided parameters.
 32  - **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
 33    specific tool invocation.
 34  - **feedback** (<code>str | None</code>) – Optional feedback message.
 35    For example, if the tool execution is rejected, this can contain the reason. Or if the tool parameters were
 36    modified, this can contain the modification details.
 37  - **final_tool_params** (<code>dict\[str, Any\] | None</code>) – Optional final parameters for the tool if execution is confirmed or modified.
 38  
 39  #### to_dict
 40  
 41  ```python
 42  to_dict() -> dict[str, Any]
 43  ```
 44  
 45  Convert the ToolExecutionDecision to a dictionary representation.
 46  
 47  **Returns:**
 48  
 49  - <code>dict\[str, Any\]</code> – A dictionary containing the tool execution decision details.
 50  
 51  #### from_dict
 52  
 53  ```python
 54  from_dict(data: dict[str, Any]) -> ToolExecutionDecision
 55  ```
 56  
 57  Populate the ToolExecutionDecision from a dictionary representation.
 58  
 59  **Parameters:**
 60  
 61  - **data** (<code>dict\[str, Any\]</code>) – A dictionary containing the tool execution decision details.
 62  
 63  **Returns:**
 64  
 65  - <code>ToolExecutionDecision</code> – An instance of ToolExecutionDecision.
 66  
 67  ## policies
 68  
 69  ### AlwaysAskPolicy
 70  
 71  Bases: <code>ConfirmationPolicy</code>
 72  
 73  Always ask for confirmation.
 74  
 75  #### should_ask
 76  
 77  ```python
 78  should_ask(
 79      tool_name: str, tool_description: str, tool_params: dict[str, Any]
 80  ) -> bool
 81  ```
 82  
 83  Always ask for confirmation before executing the tool.
 84  
 85  **Parameters:**
 86  
 87  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
 88  - **tool_description** (<code>str</code>) – The description of the tool.
 89  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
 90  
 91  **Returns:**
 92  
 93  - <code>bool</code> – Always returns True, indicating confirmation is needed.
 94  
 95  ### NeverAskPolicy
 96  
 97  Bases: <code>ConfirmationPolicy</code>
 98  
 99  Never ask for confirmation.
100  
101  #### should_ask
102  
103  ```python
104  should_ask(
105      tool_name: str, tool_description: str, tool_params: dict[str, Any]
106  ) -> bool
107  ```
108  
109  Never ask for confirmation, always proceed with tool execution.
110  
111  **Parameters:**
112  
113  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
114  - **tool_description** (<code>str</code>) – The description of the tool.
115  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
116  
117  **Returns:**
118  
119  - <code>bool</code> – Always returns False, indicating no confirmation is needed.
120  
121  ### AskOncePolicy
122  
123  Bases: <code>ConfirmationPolicy</code>
124  
125  Ask only once per tool with specific parameters.
126  
127  #### __init__
128  
129  ```python
130  __init__() -> None
131  ```
132  
133  Creates an instance of AskOncePolicy.
134  
135  #### should_ask
136  
137  ```python
138  should_ask(
139      tool_name: str, tool_description: str, tool_params: dict[str, Any]
140  ) -> bool
141  ```
142  
143  Ask for confirmation only once per tool with specific parameters.
144  
145  **Parameters:**
146  
147  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
148  - **tool_description** (<code>str</code>) – The description of the tool.
149  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
150  
151  **Returns:**
152  
153  - <code>bool</code> – True if confirmation is needed, False if already asked with the same parameters.
154  
155  #### update_after_confirmation
156  
157  ```python
158  update_after_confirmation(
159      tool_name: str,
160      tool_description: str,
161      tool_params: dict[str, Any],
162      confirmation_result: ConfirmationUIResult,
163  ) -> None
164  ```
165  
166  Store the tool and parameters if the action was "confirm" to avoid asking again.
167  
168  This method updates the internal state to remember that the user has already confirmed the execution of the
169  tool with the given parameters.
170  
171  **Parameters:**
172  
173  - **tool_name** (<code>str</code>) – The name of the tool that was executed.
174  - **tool_description** (<code>str</code>) – The description of the tool.
175  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters that were passed to the tool.
176  - **confirmation_result** (<code>ConfirmationUIResult</code>) – The result from the confirmation UI.
177  
178  ## strategies
179  
180  ### BlockingConfirmationStrategy
181  
182  Confirmation strategy that blocks execution to gather user feedback.
183  
184  #### __init__
185  
186  ```python
187  __init__(
188      *,
189      confirmation_policy: ConfirmationPolicy,
190      confirmation_ui: ConfirmationUI,
191      reject_template: str = REJECTION_FEEDBACK_TEMPLATE,
192      modify_template: str = MODIFICATION_FEEDBACK_TEMPLATE,
193      user_feedback_template: str = USER_FEEDBACK_TEMPLATE
194  ) -> None
195  ```
196  
197  Initialize the BlockingConfirmationStrategy with a confirmation policy and UI.
198  
199  **Parameters:**
200  
201  - **confirmation_policy** (<code>ConfirmationPolicy</code>) – The confirmation policy to determine when to ask for user confirmation.
202  - **confirmation_ui** (<code>ConfirmationUI</code>) – The user interface to interact with the user for confirmation.
203  - **reject_template** (<code>str</code>) – Template for rejection feedback messages. It should include a `{tool_name}` placeholder.
204  - **modify_template** (<code>str</code>) – Template for modification feedback messages. It should include `{tool_name}` and `{final_tool_params}`
205    placeholders.
206  - **user_feedback_template** (<code>str</code>) – Template for user feedback messages. It should include a `{feedback}` placeholder.
207  
208  #### run
209  
210  ```python
211  run(
212      *,
213      tool_name: str,
214      tool_description: str,
215      tool_params: dict[str, Any],
216      tool_call_id: str | None = None,
217      confirmation_strategy_context: dict[str, Any] | None = None
218  ) -> ToolExecutionDecision
219  ```
220  
221  Run the human-in-the-loop strategy for a given tool and its parameters.
222  
223  **Parameters:**
224  
225  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
226  - **tool_description** (<code>str</code>) – The description of the tool.
227  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
228  - **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call. This can be used to track and correlate the decision with a
229    specific tool invocation.
230  - **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources. Useful in web/server environments
231    to provide per-request objects (e.g., WebSocket connections, async queues, Redis pub/sub clients)
232    that strategies can use for non-blocking user interaction.
233  
234  **Returns:**
235  
236  - <code>ToolExecutionDecision</code> – A ToolExecutionDecision indicating whether to execute the tool with the given parameters, or a
237    feedback message if rejected.
238  
239  #### run_async
240  
241  ```python
242  run_async(
243      *,
244      tool_name: str,
245      tool_description: str,
246      tool_params: dict[str, Any],
247      tool_call_id: str | None = None,
248      confirmation_strategy_context: dict[str, Any] | None = None
249  ) -> ToolExecutionDecision
250  ```
251  
252  Async version of run. Calls the sync run() method by default.
253  
254  **Parameters:**
255  
256  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
257  - **tool_description** (<code>str</code>) – The description of the tool.
258  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
259  - **tool_call_id** (<code>str | None</code>) – Optional unique identifier for the tool call.
260  - **confirmation_strategy_context** (<code>dict\[str, Any\] | None</code>) – Optional dictionary for passing request-scoped resources.
261  
262  **Returns:**
263  
264  - <code>ToolExecutionDecision</code> – A ToolExecutionDecision indicating whether to execute the tool with the given parameters.
265  
266  #### to_dict
267  
268  ```python
269  to_dict() -> dict[str, Any]
270  ```
271  
272  Serializes the BlockingConfirmationStrategy to a dictionary.
273  
274  **Returns:**
275  
276  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
277  
278  #### from_dict
279  
280  ```python
281  from_dict(data: dict[str, Any]) -> BlockingConfirmationStrategy
282  ```
283  
284  Deserializes the BlockingConfirmationStrategy from a dictionary.
285  
286  **Parameters:**
287  
288  - **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
289  
290  **Returns:**
291  
292  - <code>BlockingConfirmationStrategy</code> – Deserialized BlockingConfirmationStrategy.
293  
294  ## user_interfaces
295  
296  ### RichConsoleUI
297  
298  Bases: <code>ConfirmationUI</code>
299  
300  Rich console interface for user interaction.
301  
302  #### __init__
303  
304  ```python
305  __init__(console: Console | None = None) -> None
306  ```
307  
308  Creates an instance of RichConsoleUI.
309  
310  #### get_user_confirmation
311  
312  ```python
313  get_user_confirmation(
314      tool_name: str, tool_description: str, tool_params: dict[str, Any]
315  ) -> ConfirmationUIResult
316  ```
317  
318  Get user confirmation for tool execution via rich console prompts.
319  
320  **Parameters:**
321  
322  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
323  - **tool_description** (<code>str</code>) – The description of the tool.
324  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.
325  
326  **Returns:**
327  
328  - <code>ConfirmationUIResult</code> – ConfirmationUIResult based on user input.
329  
330  #### to_dict
331  
332  ```python
333  to_dict() -> dict[str, Any]
334  ```
335  
336  Serializes the RichConsoleConfirmationUI to a dictionary.
337  
338  **Returns:**
339  
340  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
341  
342  ### SimpleConsoleUI
343  
344  Bases: <code>ConfirmationUI</code>
345  
346  Simple console interface using standard input/output.
347  
348  #### get_user_confirmation
349  
350  ```python
351  get_user_confirmation(
352      tool_name: str, tool_description: str, tool_params: dict[str, Any]
353  ) -> ConfirmationUIResult
354  ```
355  
356  Get user confirmation for tool execution via simple console prompts.
357  
358  **Parameters:**
359  
360  - **tool_name** (<code>str</code>) – The name of the tool to be executed.
361  - **tool_description** (<code>str</code>) – The description of the tool.
362  - **tool_params** (<code>dict\[str, Any\]</code>) – The parameters to be passed to the tool.