Skip to content

feat(agents): add AgentSession for stateful multi-turn async conversations#2593

Draft
ks93 wants to merge 1 commit into
masterfrom
001-agents-session
Draft

feat(agents): add AgentSession for stateful multi-turn async conversations#2593
ks93 wants to merge 1 commit into
masterfrom
001-agents-session

Conversation

@ks93
Copy link
Copy Markdown
Contributor

@ks93 ks93 commented Apr 24, 2026

Summary

  • Adds AgentSession class (cognite/client/data_classes/agents/session.py) that stores agent external ID, actions, and conversation cursor for multi-turn async chat.
  • Adds AgentsAPI.create_session() as a plain def factory method (not async def) — this keeps it out of the codegen sync path, so the sync client is untouched.
  • AgentSession.chat() automatically threads the cursor from each response into the next request; callers manage only messages, not cursor state.

Behavior

  • Cursor advances only on a successful response — a failed await session.chat(...) leaves the cursor intact so the call can be retried.
  • A null/missing cursor in the response retains the last known cursor.
  • Unknown kwargs to create_session() are silently accepted for forward compatibility.
  • AgentSession is exported from cognite.client.data_classes.agents.

Test plan

  • 16 new async unit tests in tests/tests_unit/test_api/test_agents.py covering cursor threading, failure isolation, null-cursor retention, actions forwarding, action-result round-trips, ToolConfirmationCall pass-through, and scope guards (read-only cursor, sync client exclusion, no reset method)
  • Sync client verified: hasattr(sync_client.agents, "create_session") is False
  • Codegen verified: _sync_api/agents/agents.py has no new methods (hash-only update)
  • All pre-commit hooks pass (ruff, mypy, custom-checks, sync-codegen, pydoclint)

…tions

Adds `AgentSession` (async-only) and `AgentsAPI.create_session()` so callers
on `AsyncCogniteClient` can conduct multi-turn conversations without manually
threading the cursor between requests.

- `create_session()` is a regular `def` (not async), which keeps it out of the
  codegen sync path entirely — the sync client is unchanged.
- `AgentSession.chat()` advances the cursor only on success; failures leave it
  intact so the call can be retried safely.
- `cursor=None` response retains the last non-null cursor.
- Unknown kwargs to `create_session()` are silently accepted for forward
  compatibility.
@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 24, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.79%. Comparing base (43efd75) to head (9148112).
⚠️ Report is 8 commits behind head on master.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2593      +/-   ##
==========================================
+ Coverage   92.76%   92.79%   +0.02%     
==========================================
  Files         480      481       +1     
  Lines       48511    48685     +174     
==========================================
+ Hits        45003    45176     +173     
- Misses       3508     3509       +1     
Files with missing lines Coverage Δ
cognite/client/_api/agents/agents.py 100.00% <100.00%> (ø)
cognite/client/_sync_api/agents/agents.py 100.00% <ø> (ø)
cognite/client/data_classes/agents/__init__.py 100.00% <100.00%> (ø)
cognite/client/data_classes/agents/session.py 100.00% <100.00%> (ø)
tests/tests_unit/test_api/test_agents.py 100.00% <100.00%> (ø)

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant