feat(agents): add timeout parameter to chat method

[ks93]

Adds a timeout parameter to the agents.chat() method to handle long-running agent executions. The method now uses _do_request() with a default timeout of 60 seconds, allowing endpoint-specific timeout configuration instead of relying solely on global client timeout settings.

[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.95%. Comparing base (787926e) to head (05aec6e).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2316      +/-   ##
==========================================
- Coverage   90.96%   90.95%   -0.02%     
==========================================
  Files         192      192              
  Lines       26133    26133              
==========================================
- Hits        23773    23768       -5     
- Misses       2360     2365       +5     

Files with missing lines	Coverage Δ
cognite/client/_api/agents/agents.py	100.00% <100.00%> (ø)

... and 3 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.

[haakonvt]

I’m okay with introducing a higher timeout setting for these agent APIs that we expect to be «long running»

[ks93]

I’m okay with introducing a higher timeout setting for these agent APIs that we expect to be «long running»

That would be great @haakonvt . How would we do that?

[haakonvt]

LGTM

[thorkildcognite]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a timeout parameter to the agents.chat() method, which is a good addition for handling potentially long-running agent executions. The implementation correctly passes the timeout to the underlying request method, and the changes are well-tested. I've added a couple of suggestions to improve maintainability by replacing the magic number for the default timeout with a constant, in line with the repository's style guide.

[gemini-code-assist]

To improve maintainability and avoid using a magic number, the default timeout value 60 should be defined as a constant. This aligns with the style guide's convention for constants.¹

You can define it at the module or class level, for example:
_DEFAULT_AGENT_CHAT_TIMEOUT = 60

And then use it in the method signature:
timeout: int = _DEFAULT_AGENT_CHAT_TIMEOUT

Style Guide References

Footnotes

1. The style guide specifies that constants should be named in UPPER_SNAKE_CASE. Using a constant for the default timeout avoids magic numbers, improving readability and making it easier to update the value in the future. (link) ↩

[erlendvollset]

I don't mind letting the user increase the timeout for this API if this is how we want the API to behave, but I would still like to express some concerns around the API design. Having long-running HTTP requests introduces some problems:

• ties up connection resources in the service for a long time
• ties up concurency/rate-limiting resources in the service for a long time
• makes horizontal scaling harder, since you need to wait for long-running ongoing requests to finish
• services on the request path will usually set lower timeouts (e.g. emissary and nginx have 60 or 90 sec by default), so you need to ensure your whole stack allows increased timeouts

Have you considered building an async API for this use case? i.e. one endpoint to start the task and another to poll for results.

[thorkildcognite]

How long would the user usually want to bump this? Remembering that I believe there is a general 90 second timeout in the API-gateway already?

[ks93]

@miladh @andeplane

See comments from Erlend and Thorkild.