- Anthropic vừa ship SessionStore adapter cho Agent SDK (TS + Python) với reference implementation cho S3, Redis, và Postgres.
- Session tạo trên host này có thể resume trên host khác — serverless và autoscale giờ đã khả thi.
TL;DR
Claude Agent SDK vừa ship SessionStore adapter ở cả TypeScript (v0.2.113, 17-04-2026) và Python (v0.1.64, 20-04-2026). Bạn có thể mirror toàn bộ transcript session sang backend ngoài — S3, Redis, Postgres, hay bất kỳ store nào bạn tự viết — để session tạo trên host này resume được trên host khác. Anthropic publish 3 reference adapter dưới dạng copy-in trong examples/session-stores/. Tính năng này mở khóa serverless, autoscale, và multi-host deployment cho agent — thứ trước đây gần như không khả thi vì session transcript bị khóa vào filesystem local.
What's new
Trước đây SDK chỉ ghi session xuống ~/.claude/projects/<encoded-cwd>/*.jsonl trên disk. Resume cross-host nghĩa là bạn phải tự copy file .jsonl sang máy mới, đúng cwd, đúng path. Với serverless function hay autoscaled pod, chuyện này gần như bất khả thi.
Bây giờ bạn chỉ cần truyền một sessionStore vào query():
import { query, InMemorySessionStore } from "@anthropic-ai/claude-agent-sdk";
const store = new InMemorySessionStore();
for await (const message of query({
prompt: "List the TypeScript files under src/",
options: { sessionStore: store },
})) {
if (message.type === "result") {
console.log(message.session_id);
}
}
Lần sau, từ bất kỳ host nào attach cùng store đó + pass resume: sessionId là agent có đầy đủ context của lần trước — files đã đọc, analysis đã chạy, quyết định đã ra.
Technical facts
Interface cực gọn — chỉ 2 method bắt buộc, 3 optional:
| Method | Required | Khi nào SDK gọi |
|---|---|---|
append(key, entries) | Có | Sau mỗi batch transcript entry được ghi xuống local. |
load(key) | Có | Một lần trước khi subprocess spawn, khi resume được set. |
listSessions(projectKey) | Không | Khi app gọi listSessions() hoặc continue: true. |
delete(key) | Không | Khi app gọi deleteSession(). Bỏ qua cho append-only backend. |
listSubkeys(key) | Không | Khi resume để khôi phục subagent transcript. |
SessionKey có shape { projectKey, sessionId, subpath? }. subpath undefined = main transcript; subpath = "subagents/agent-<id>" = transcript subagent.
Một điểm quan trọng: đây là dual-write architecture. Subprocess Claude Code luôn ghi local disk trước, SDK mới forward batch sang append(). Nếu append() reject hay timeout, SDK emit message { type: "system", subtype: "mirror_error" } vào iterator và tiếp tục chạy — không retry, không chặn agent. Local vẫn durable, nhưng bạn phải tự monitor mirror_error để phát hiện data loss ở store.
Comparison — 3 reference adapters
| Adapter | Backend client | Storage model |
|---|---|---|
S3SessionStore | @aws-sdk/client-s3 | Một JSONL part file mỗi lần append(); load() list + sort + concat. |
RedisSessionStore | ioredis | RPUSH/LRANGE list per transcript + sorted-set session index. |
PostgresSessionStore | pg (TS) / asyncpg (Python) | Một row per entry trong table jsonb, order theo BIGSERIAL. |
Rule of thumb: Postgres cho agent small-to-medium với moderate concurrency (dễ query, dễ audit bằng SQL). Redis cho session interactive ngắn hạn cần latency thấp. S3 cho long-running background task với nhiều tool result lớn.
Cả 3 đều không publish lên npm/PyPI — copy file trong examples/session-stores/<backend>/ vào project của bạn và install client tương ứng. Đây là design intentional: mỗi team control credential, TLS, region, pooling theo cách của riêng mình.
Use cases
- Serverless agent endpoints (Lambda, Vercel Functions, Cloud Run): user gõ message → function spawn → resume từ Redis → reply → append mirror → function chết. Không cần sticky session.
- Autoscaled agent fleet trên K8s: load balancer route user đi bất kỳ đâu; bất kỳ pod nào cũng resume được bằng
sessionId + store. - CI coding agent: GitHub Actions job A tạo session, job B resume và apply patch. Shared Postgres làm source of truth.
- Compliance-heavy env: transcript ngồi trong S3 bucket đã có SSE-KMS + lifecycle + IAM sẵn, không cần đụng
~/.claude/của dev. - Audit & replay: Postgres
jsonbcho phép query lịch sử agent bằng SQL, build internal tooling đọc transcript.
Limitations & pricing
- Không retry khi mirror fail. Batch lỗi = mất vĩnh viễn khỏi store (local vẫn còn). Phải monitor
mirror_errormessage. - Không combine được với
persistSession: false(vì mirror cần local write) hoặcenableFileCheckpointing(file-history blob chỉ ghi local). SDK throw nếu set cả hai. - Retention là trách nhiệm của adapter. SDK không bao giờ delete từ store. Tự implement TTL, S3 lifecycle policy, hoặc scheduled cleanup theo compliance requirement.
- Reference adapter KHÔNG published. Copy-in only. Vừa nhẹ gánh SDK, vừa buộc user đọc code trước khi chạy production.
- Pricing: tính năng miễn phí trong SDK; chi phí nằm ở backend bạn chọn (S3 PUT/GET, Redis memory, Postgres storage). Agent SDK usage vẫn charge theo Anthropic API pricing thông thường.
Cả hai SDK đều ship conformance harness — 13-contract test suite assert behavioral contract mà append/load và các method optional phải thỏa. Python dùng trực tiếp: await run_session_store_conformance(MyStore). TypeScript copy examples/session-stores/shared/conformance.ts vào test suite. Test cho method optional auto-skip khi adapter chưa implement.
What's next
Đây là response trực tiếp cho Issue #97 — feature request mở từ lâu về "customizable session storage backend cho cloud/Kubernetes deployment". Bây giờ Agent SDK ngang hàng với framework agent khác về mặt deployment story.
Signal đáng theo dõi tiếp: (1) reference adapter có thể được extract thành package riêng sau khi feedback ổn định; (2) TypeScript SDK V2 preview (với createSession() và send/stream pattern) sẽ đưa sessionStore lên first-class ở client level; (3) managed retention/TTL helper vẫn là gap logic cần fill — hiện tại mỗi team tự build.
Nguồn: Claude Agent SDK docs — Persist sessions to external storage, examples/session-stores, TS SDK releases, Python SDK releases, Noah Zweben announcement.