docs: add tool confirmation flow example to agents chat()#2543
Conversation
Add a docstring example showing how to detect and respond to a ToolConfirmationCall when using integration tools (Call Function, Run Python code, Call REST API) that require explicit user approval. Also improve ToolConfirmationCall and ToolConfirmationResult docstrings to explain which tools trigger confirmation and how to use them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #2543 +/- ##
==========================================
- Coverage 93.43% 93.42% -0.01%
==========================================
Files 478 478
Lines 48230 48230
==========================================
- Hits 45062 45060 -2
- Misses 3168 3170 +2
🚀 New features to boost your workflow:
|
Clarify that some tools require explicit confirmation before execution so the agent chat response flow is easier to understand.
ks93
added
the
waiting-for-risk-review
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request improves the developer experience for the Atlas AI agents SDK by providing clear guidance on how to handle tool confirmation requests. By adding practical examples and clarifying the documentation for confirmation-related classes, it addresses common user confusion regarding the interaction flow for sensitive tools. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation for agent tool confirmations, adding usage examples and clarifying the purpose of ToolConfirmationCall and ToolConfirmationResult. A review of the new docstring example identified potential logic errors, specifically a possible TypeError if action_calls is None and incorrect cursor management when processing multiple actions within a loop.
Update the generated sync agents API so it stays aligned with the async agents chat documentation changes and passes sync codegen verification.
Align the agents documentation changes with repo formatting, docstring, and sync codegen requirements so CI passes without hook-generated diffs.
Update the tool confirmation example to guard against missing action calls and batch confirmation results so the cursor usage stays consistent when multiple actions are returned.
| ... print(f"Tool: {action.tool_name}, type: {action.tool_type}") | ||
| ... print(f"Arguments: {action.tool_arguments}") |
There was a problem hiding this comment.
This should ideally use the input function
haakonvt
added
risk-review-ongoing
3 participants
Summary
AgentsAPI.chat()showing the fullToolConfirmationCall→ToolConfirmationResultflow for integration tools (Call Function, Run Python code, Call REST API)ToolConfirmationCalldocstring to explain which tools trigger confirmation and what to do with itToolConfirmationResultdocstring to explain usage and the importance of passing thecursorContext
Users calling Atlas AI agents via the SDK are confused when they receive a
ToolConfirmationCallaction in the response and don't know how to handle it. The existing docstring examples only covered basic chat and client-side tool actions — this adds the missing confirmation flow.Relates to feedback from: topic-ai-agents Slack thread (Nov 2025).
Test plan
python -m pytest --doctest-modules cognite/client/_api/agents/🤖 Generated with Claude Code