feat(context): add context_manager="auto" facade on Agent

[lizradway]

Description

Adds contextManager: "auto" / context_manager="auto" as an opt-in parameter on Agent in both SDKs. When set, it wires up the benchmark-winning context management configuration:

• ContextOffloader(storage=InMemoryStorage(), maxResultTokens=1500, previewTokens=750) — caches oversized tool results, keeps truncated previews in context, provides retrieve_offloaded_content tool
• SummarizingConversationManager(summaryRatio=0.3, compressionThreshold=0.85) — summarizes older messages on context overflow, proactively compresses at 85% context window usage

Coexistence rules:

• If user also provides conversationManager, theirs is used (offloader still added)
• If user already has a ContextOffloader in their plugins list, it's not overridden
• Throws with stateful models (they manage context server-side)

from strands import Agent

agent = Agent(model="us.anthropic.claude-sonnet-4-6-v1", context_manager="auto")

import { Agent } from '@strands-agents/sdk'

const agent = new Agent({ model: 'us.anthropic.claude-sonnet-4-6-v1', contextManager: 'auto' })

Related Issues

strands-agents/docs#831

Documentation PR

N/A — docs PR (strands-agents/docs#831) covers the design. User-facing docs page to follow once this ships.

Type of Change

New feature

Testing

• Python: 16 unit tests covering all resolution paths, 502 existing agent tests pass
• TypeScript: 10 unit tests covering all resolution paths, 122 existing agent tests pass
• hatch fmt --linter --check passes (ruff + mypy)
• tsc --noEmit passes
• Merged with latest upstream/main, conflicts resolved, all tests re-verified
• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Comment

Clean, well-scoped feature that aligns with the SDK tenets (simple at any scale, extensible by design). The coexistence rules are well thought out.

Review Themes

• Validation ordering: The stateful model check fires after objects are already constructed, and the error message doesn't reflect the new context_manager trigger.
• Runtime safety: No runtime guard against invalid context_manager values (only type-checked); per tenet 4, a helpful ValueError would be appropriate.
• Documentation completeness: The proactive_compression threshold (0.85) is a meaningful behavioral default that should be surfaced in the docstring and the _resolve_context_manager method should have a full Google-style docstring.
• Test reliance on private internals: Most assertions reach into _-prefixed attributes; this is pragmatic given the current API surface but worth acknowledging for future maintenance.
• API review process: This introduces a new public parameter on Agent — per API_BAR_RAISING.md, consider adding the needs-api-review label.

Nice feature that makes context management accessible in a single parameter — well aligned with "simple things should be simple."

[github-actions]

Assessment: Approve

All previous feedback has been addressed — the code now validates before constructing, has accurate error messages, includes runtime guards for unsupported values, and has complete documentation.

Changes verified

• ✅ Stateful model validation occurs before _resolve_context_manager
• ✅ Error message mentions both context_manager and conversation_manager
• ✅ Runtime ValueError for unsupported context_manager values with test coverage
• ✅ Docstring includes compression_threshold=0.85
• ✅ _resolve_context_manager has full Google-style docstring with Raises section
• ✅ MyPlugin in tests properly inherits from Plugin ABC

One remaining consideration: this introduces a new public API parameter on Agent. Per API_BAR_RAISING.md, the needs-api-review label may still be appropriate depending on team norms for moderate-scope changes.

[github-actions]

Assessment: Approve

Clean, opt-in facade that composes benchmark-validated context management primitives behind a single parameter. Pay-for-play design (existing agents unaffected), proper validation ordering, and comprehensive cross-SDK test coverage.

Remaining Items

• Missing TS export (inline comment on src/index.ts:16): ContextManagerStrategy should be re-exported for parity with ToolExecutorStrategy
• Durability caveat (inline comment on agent.py:219): Docstring should note that InMemoryStorage doesn't persist across restarts — users pairing with session_manager need explicit ContextOffloader with durable storage
• API process: Consider needs-api-review label per API_BAR_RAISING.md for this new public Agent parameter (moderate scope)

Well-aligned with "simple things should be simple" and "provide both low-level and high-level APIs" tenets.

[github-actions]

Assessment: Approve

Well-designed opt-in facade that composes benchmark-validated context management primitives (ContextOffloader + SummarizingConversationManager) behind a single context_manager="auto" parameter. Pay-for-play design, proper validation, and comprehensive cross-SDK test coverage.

Review Details

• API design: Aligns with "simple things should be simple" and "extensible by design" tenets — the facade composes primitives without hiding them, and the coexistence rules are well thought out
• Missing export (1 inline comment): ContextManagerStrategy type should be re-exported from src/index.ts per "Prefer Flat Namespaces" decision
• Documentation gap (1 inline comment): Docstring should warn about InMemoryStorage non-durability when paired with session_manager per tenet 4
• API process: This adds a new public parameter on Agent (moderate scope per API_BAR_RAISING.md). Consider adding the needs-api-review label if not already tracked via the linked docs issue

The get_args(ContextManagerStrategy) pattern for runtime validation derived from the type definition is a nice touch for keeping type and validation in sync.

[github-actions]

Assessment: Approve

Clean opt-in facade that composes ContextOffloader + SummarizingConversationManager behind a single context_manager="auto" parameter. The design aligns with "Provide Both Low-Level and High-Level APIs" and "Pay for Play" decisions — existing agents are unaffected, and users can always drop to explicit primitives for fine-grained control.

Review Details

• Missing exports (2 inline comments): ContextManagerStrategy should be re-exported from both strands-ts/src/index.ts and strands-py/src/strands/agent/__init__.py per "Prefer Flat Namespaces" decision. Users who type-annotate wrapper functions need access without reaching into internal module paths.
• Durability caveat (1 inline comment): The TS docstring has the same gap flagged in the open Python thread — InMemoryStorage + sessionManager creates dangling offload references on session restore. Both SDKs should document this.
• Prior feedback: All 12 resolved threads have been addressed cleanly — validation ordering, runtime guards, constants extraction, plugin ordering parity, and full docstrings are all solid.

The implementation is well-structured, test coverage is comprehensive across both SDKs, and the coexistence semantics (user CM precedence, offloader dedup, stateful model guard) are correct and consistent.

[github-actions]

Assessment: Approve

Well-designed opt-in facade — all prior feedback addressed, cross-SDK consistency is solid, durability caveat now documented in both SDKs.

One remaining item

• Missing export: ContextManagerStrategy should be re-exported from src/index.ts (TS) and strands/agent/__init__.py (Python) per "Prefer Flat Namespaces" decision. ToolExecutorStrategy is already exported at those levels — this should be consistent.