Skip to content

Commit b76c56b

Browse files
andeplaneclaudeks93
authored
docs: add tool confirmation flow example to agents chat() (#2543)
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Kelvin Sundli <kelvin.sundli@cognite.com>
1 parent ef5ac04 commit b76c56b

3 files changed

Lines changed: 74 additions & 5 deletions

File tree

‎cognite/client/_api/agents/agents.py‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -341,6 +341,36 @@ async def chat(
341341
... cursor=response.cursor,
342342
... actions=[add_numbers_action],
343343
... )
344+
345+
Handle tool confirmation for integration tools (Call Function, Run Python code, Call REST API):
346+
347+
>>> from cognite.client.data_classes.agents import (
348+
... ToolConfirmationCall,
349+
... ToolConfirmationResult,
350+
... )
351+
>>> response = client.agents.chat(
352+
... agent_external_id="my_agent",
353+
... messages=Message("Run the data quality check function"),
354+
... )
355+
>>> if response.action_calls:
356+
... confirmations = []
357+
... for action in response.action_calls:
358+
... if isinstance(action, ToolConfirmationCall):
359+
... # Inspect each tool call before deciding
360+
... print(f"Tool: {action.tool_name}, type: {action.tool_type}")
361+
... print(f"Arguments: {action.tool_arguments}")
362+
... confirmations.append(
363+
... ToolConfirmationResult(
364+
... action_id=action.action_id,
365+
... status="ALLOW", # or "DENY" to cancel
366+
... )
367+
... )
368+
... if confirmations:
369+
... response = client.agents.chat(
370+
... agent_external_id="my_agent",
371+
... messages=confirmations,
372+
... cursor=response.cursor,
373+
... )
344374
"""
345375
self._warnings.warn()
346376

‎cognite/client/_sync_api/agents/agents.py‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""
22
===============================================================================
3-
74efd4d9ffccd91e350abcb621a40578
3+
bfc6535f11bf8b175836aebca409eb8b
44
This file is auto-generated from the Async API modules, - do not edit manually!
55
===============================================================================
66
"""
@@ -323,6 +323,36 @@ def chat(
323323
... cursor=response.cursor,
324324
... actions=[add_numbers_action],
325325
... )
326+
327+
Handle tool confirmation for integration tools (Call Function, Run Python code, Call REST API):
328+
329+
>>> from cognite.client.data_classes.agents import (
330+
... ToolConfirmationCall,
331+
... ToolConfirmationResult,
332+
... )
333+
>>> response = client.agents.chat(
334+
... agent_external_id="my_agent",
335+
... messages=Message("Run the data quality check function"),
336+
... )
337+
>>> if response.action_calls:
338+
... confirmations = []
339+
... for action in response.action_calls:
340+
... if isinstance(action, ToolConfirmationCall):
341+
... # Inspect each tool call before deciding
342+
... print(f"Tool: {action.tool_name}, type: {action.tool_type}")
343+
... print(f"Arguments: {action.tool_arguments}")
344+
... confirmations.append(
345+
... ToolConfirmationResult(
346+
... action_id=action.action_id,
347+
... status="ALLOW", # or "DENY" to cancel
348+
... )
349+
... )
350+
... if confirmations:
351+
... response = client.agents.chat(
352+
... agent_external_id="my_agent",
353+
... messages=confirmations,
354+
... cursor=response.cursor,
355+
... )
326356
"""
327357
return run_sync(
328358
self.__async_client.agents.chat(

‎cognite/client/data_classes/agents/chat.py‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -231,13 +231,18 @@ def _load_call(cls, data: dict[str, Any]) -> ClientToolCall:
231231
class ToolConfirmationCall(ActionCall):
232232
"""A tool confirmation request from the agent.
233233
234+
Some tools require explicit user confirmation before execution, to prevent unintended or destructive actions.
235+
These tools include Call Function, Run Python code, and Call REST API.
236+
When an agent wants to run one of these tools, this action is included in the response
237+
instead of the final result. Respond with a :class:`ToolConfirmationResult` using ``status="ALLOW"`` to proceed or ``status="DENY"`` to cancel.
238+
234239
Args:
235240
action_id (str): The unique identifier for this action call.
236-
content (MessageContent): The confirmation message content.
241+
content (MessageContent): The human-readable confirmation message from the agent.
237242
tool_name (str): The name of the tool requiring confirmation.
238243
tool_arguments (dict[str, object]): The arguments for the tool call.
239244
tool_description (str): Description of what the tool does.
240-
tool_type (str): The type of tool (e.g., "runPythonCode", "callRestApi").
245+
tool_type (str): The type of tool (e.g., "callFunction", "runPythonCode", "callRestApi").
241246
details (dict[str, object] | None): Optional additional details about the tool call.
242247
"""
243248

@@ -403,10 +408,14 @@ def _load(cls, data: dict[str, Any]) -> ClientToolResult:
403408

404409
@dataclass(frozen=True, slots=True)
405410
class ToolConfirmationResult(ActionResult):
406-
"""Result of a tool confirmation request.
411+
"""Result of a tool confirmation request, sent back to the agent.
412+
413+
Use this to respond to a :class:`ToolConfirmationCall` received in the agent response.
414+
Pass ``status="ALLOW"`` to let the agent execute the tool, or ``status="DENY"`` to cancel it.
415+
Always include the ``cursor`` from the confirmation response when sending this result.
407416
408417
Args:
409-
action_id (str): The ID of the action being responded to.
418+
action_id (str): The ID of the :class:`ToolConfirmationCall` being responded to.
410419
status (Literal['ALLOW', 'DENY']): Whether to allow or deny the tool execution.
411420
"""
412421

0 commit comments

Comments
 (0)