Skip to content

feat(integration/langgraph): implement put_writes, delete_thread, and async context manager - #49

Merged
Zhiyue-Wang merged 1 commit into
huaweicloud:mainfrom
Isuzu-ren:feature/langgraph-put_writes-delete_thread
Aug 28, 2026
Merged

Zhiyue-Wang merged 1 commit into
huaweicloud:mainfrom
Isuzu-ren:feature/langgraph-put_writes-delete_thread

Conversation

@Isuzu-ren

Copy link
Copy Markdown
Contributor

Description

This PR completes the LangGraph BaseCheckpointSaver implementation by filling in four stub/outdated methods: put_writes/aput_writes, delete_thread/adelete_thread, and adds async context manager support (aclose/__aenter__/__aexit__).

Background

put_writes and aput_writes were stubs that only logged warnings, which meant LangGraph's interrupt/resume and crash-recovery flows (Pregel) could not function. delete and adelete used an outdated signature (delete(config)) that no longer matched the current BaseCheckpointSaver interface (delete_thread(thread_id)), so LangGraph never called them.

Changes

src/agentarts/sdk/integration/langgraph/saver.py

  • put_writes / aput_writes: Serialize writes via serde.dumps_typed + base64, pack into a TextMessage(role="system", content="pending_writes", meta=...) and store in a dedicated writes session (UUID5-derived from the main session ID). If the writes session does not exist (HTTP 404), it is automatically created and the write is retried. Non-404 errors are logged but do not crash the caller.
  • delete_thread / adelete_thread: Delete both the main session and the writes session via delete_session. Writes session deletion failure is logged at debug level (it may not exist). _persisted_count is cleaned up.
  • _writes_session_id(session_id): Static helper that returns str(uuid.uuid5(DNS_NAMESPACE, session_id)), ensuring the writes session ID is a valid 36-char UUID as required by the backend.
  • _extract_pending_writes(messages, checkpoint_id): Reads write messages from the writes session, filters by checkpoint_id, and deduplicates by (task_id, write_idx) — regular writes (idx >= 0) first-wins (idempotent skip), special writes (ERROR/INTERRUPT/RESUME/SCHEDULED, idx < 0) last-wins (always overwrite), matching InMemorySaver semantics.
  • get_tuple / aget_tuple / list / alist: Retrieve pending writes from the writes session and attach to CheckpointTuple. Retrieval failure is logged at debug level and does not break main checkpoint retrieval.
  • aclose / __aenter__ / __aexit__: Async context manager support. aclose() closes both the sync and async clients. Symmetric with the existing sync close() / __enter__ / __exit__.

tests/unit/sdk/integration/test_langgraph.py

  • Updated test_saver_methods_exist to assert delete_thread and adelete_thread instead of the old delete and adelete.

Design rationale: separate writes session

Writes are stored in a dedicated {session_id}__writes session (UUID5-derived) rather than the main session because: (1) delta tracking integrity — _persisted_count tracks conversation messages only, mixed writes would inflate get_last_k_messages total and cause duplicate message writes in put(); (2) metadata extraction — get_tuple uses messages[-1] to extract checkpoint metadata, mixed writes would corrupt that; (3) no filter needed — conversation and writes are cleanly separated.

Verification

The implementation was verified against the BaseCheckpointSaver interface contract with 14 mock-based tests covering put_writes, aput_writes, delete_thread, adelete_thread, pending_writes roundtrip serialization/deserialization, dedup semantics for regular and special writes, APIException 404 auto-retry (both sync and async), and sync/async context managers. All 14 tests pass, and the full official test suite (23 tests) passes without regression. Ruff lint is clean.

- saver.py: implement put_writes/aput_writes to persist pending writes in a dedicated UUID5-derived session (auto-recreate on 404)
- saver.py: rename delete/adelete to delete_thread/adelete_thread per the current LangGraph BaseCheckpointSaver interface
- saver.py: attach pending_writes to CheckpointTuple in get_tuple, aget_tuple, list, alist
- saver.py: add aclose/__aenter__/__aexit__ async context management
- test_langgraph.py: assert delete_thread/adelete_thread methods exist
@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 8.72483% with 136 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@659d1b4). Learn more about missing BASE report.

Files with missing lines Patch % Lines
src/agentarts/sdk/integration/langgraph/saver.py 8.72% 136 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.
Additional details and impacted files
@@           Coverage Diff           @@
##             main      #49   +/-   ##
=======================================
  Coverage        ?   53.31%           
=======================================
  Files           ?       95           
  Lines           ?     7959           
  Branches        ?     1224           
=======================================
  Hits            ?     4243           
  Misses          ?     3423           
  Partials        ?      293           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Zhiyue-Wang
Zhiyue-Wang merged commit 3a9ec7d into huaweicloud:main Aug 28, 2026
6 checks passed
@Isuzu-ren
Isuzu-ren deleted the feature/langgraph-put_writes-delete_thread branch August 31, 2026 01:33
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.

3 participants