feat(agents): update agents sdk to use agentExternalId instead of now deprecated agentId

[ks93]

Description

This PR updates the Agents API client to align with server-side changes, introducing support for agentExternalId while maintaining backward compatibility for the deprecated agentId. Requests now send agentExternalId.

Checklist:

• Tests added/updated.
• Documentation updated. Documentation is generated from docstrings - these must be updated according to your change.
  If a new method has been added it should be referenced in cognite.rst in order to generate docs based on its docstring.
• The PR title follows the Conventional Commit spec.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.76%. Comparing base (317439b) to head (875ab3a).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2347      +/-   ##
==========================================
- Coverage   90.78%   90.76%   -0.02%     
==========================================
  Files         170      170              
  Lines       25662    25665       +3     
==========================================
- Hits        23297    23296       -1     
- Misses       2365     2369       +4     

Files with missing lines	Coverage Δ
cognite/client/_api/agents/agents.py	100.00% <ø> (ø)
cognite/client/data_classes/agents/agents.py	100.00% <ø> (ø)
cognite/client/data_classes/agents/chat.py	98.48% <100.00%> (+0.03%)	⬆️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ks93]

@cursor

1. Docs not updated?
2. Even if user uses agent_id for a while more, only use agentExternalId with the API (and update PR description)
3. Include deprecation warning in docstrings.
4. Agent class not updated?

[cursor]

I updated the AgentsAPI.chat method to align with server-side deprecation of agentId, now exclusively sending agentExternalId. This change ensures future compatibility, clarifies external_id usage in agent data classes, and updates documentation to reflect the new preferred identifier.

• I modified the chat method in cognite/client/_api/agents/agents.py to remove the deprecated agentId from the request body, now exclusively sending agentExternalId.
• I updated the docstring for the agent_id parameter in AgentsAPI.chat and the agent_id attribute in AgentChatResponse (cognite/client/data_classes/agents/chat.py) to indicate its deprecation and future removal.
• I added a new agent_external_id attribute to AgentChatResponse in cognite/client/data_classes/agents/chat.py as the preferred way to access the agent's identifier.
• I clarified in the docstrings of AgentCore, AgentUpsert, and Agent in cognite/client/data_classes/agents/agents.py that their external_id is used as agentExternalId in the chat API.
• I added a warning directive to docs/source/agents.rst to inform users about the server-side deprecation of agentId.
• I updated the unit test in tests/tests_unit/test_api/test_agents_chat.py to assert that agentId is no longer present in the JSON payload sent to the API.

---

 

_{Learn more about Cursor Agents}