feat(strands-memory): add event metadata support to AgentCoreMemorySessionManager by tejaskash · Pull Request #339 · aws/bedrock-agentcore-sdk-python

tejaskash · 2026-03-13T20:48:41Z

Summary

Adds user-supplied event metadata support to AgentCoreMemorySessionManager (Phase 1 of #149).

Static metadata:

New default_metadata field on AgentCoreMemoryConfig — attaches custom key-value metadata to every message event

Dynamic metadata (for traceId / Langfuse integration):

New metadata_provider field — a callable invoked at each event creation, so it can return per-invocation values (e.g. current traceId). This is needed because Strands controls the append_message → create_message call path, so users can't pass per-call kwargs through agent().
Merge precedence: default_metadata < metadata_provider() < per-call metadata kwarg < internal keys

Infrastructure:

_build_metadata() helper with validation: rejects reserved keys (stateType, agentId), enforces 15-key API limit
Refactors internal _message_buffer from raw tuple to BufferedMessage NamedTuple for clarity and extensibility
Metadata flows through both immediate-send and batched flush paths

Usage example (Langfuse traceId)

from langfuse.decorators import langfuse_context

config = AgentCoreMemoryConfig(
    memory_id=MEM_ID,
    session_id=SESSION_ID,
    actor_id=ACTOR_ID,
    metadata_provider=lambda: {
        "traceId": {"stringValue": langfuse_context.get_current_trace_id() or ""}
    },
)
sm = AgentCoreMemorySessionManager(agentcore_memory_config=config, region_name="us-east-1")
agent = Agent(session_manager=sm)
agent("Hello!")  # Event gets the current traceId automatically

Test plan

11 new unit tests in TestMetadataSupport (default metadata, per-call, merge precedence, reserved keys, max keys, no-metadata, batched, blob, provider called per event, provider merge with defaults, provider reserved keys rejected)
3 new integration tests with positive/negative filter assertions (metadata round-trip, session resume, dynamic traceId with disjoint event sets)
123 existing unit tests pass unchanged (buffer tuple → BufferedMessage migration)
Full suite: 1098 tests pass, 0 failures

…ntCoreMemorySessionManager Allow users to attach custom key-value metadata to conversation events via a new `default_metadata` config field and per-call `metadata` kwarg. Metadata is merged (per-call > config defaults > internal) and validated against reserved keys and the 15-key API limit. Also refactors the internal message buffer from a raw tuple to a `BufferedMessage` NamedTuple for clarity and extensibility. Closes #149 (Phase 1: Metadata)

jariy17 · 2026-03-13T21:10:39Z

src/bedrock_agentcore/memory/integrations/strands/config.py

            Default is "user_context".
        filter_restored_tool_context: When True, strip historical toolUse/toolResult blocks from
            restored messages before loading them into Strands runtime memory. Default is False.
+        default_metadata: Optional default metadata key-value pairs to attach to every message event.


Does this actually solve the customer's ask?
What if they need different metadata for each message event? Also, what exactly do they mean by "message_event" — are they
referring to memory records, AgentCore Memory events, or individual conversation turns? Are they trying to attach a distinct metadata field to each conversation turn?

are we sure this is the interface the customer is looking for? Could we ask them to send an example code block of the support they want?

Yes, it solves the ask. metadata_provider is a callable invoked at each create_message(), so each event gets whatever traceId is current at that moment. We have an integration test confirming two invocations with different traceIds produce disjoint, independently filterable event sets.

Per-turn metadata works out of the box with batch_size=1 (the default) since each turn = its own event. With batch_size > 1 multiple turns collapse into one event, so the last traceId wins — but that's an inherent tradeoff of batching, not a metadata limitation.

The customer is talking about STM events, not LTM records (those are extracted async and don't carry event metadata).

Yes — the customer's use case is tagging events with a traceId from Langfuse that changes per invocation. metadata_provider (a callable) gives them exactly that. We have an integ test that confirms two invocations with different traceIds produce disjoint event sets filterable by list_events.

…n metadata Add `metadata_provider` config field — a callable invoked at each event creation, enabling dynamic metadata like traceId that changes per agent invocation. This solves the Langfuse/user-feedback use case where a static `default_metadata` is insufficient because Strands controls the append_message → create_message call path. Merge precedence: default_metadata < metadata_provider() < per-call kwargs < internal keys.

Hweinstock · 2026-03-13T21:11:18Z

src/bedrock_agentcore/memory/integrations/strands/README.md

+    session_id=SESSION_ID,
+    actor_id=ACTOR_ID,
+    default_metadata={
+        "project": {"stringValue": "atlas"},


would we be able to build this map on behalf of the customer? It feels very verbose.

Ex:
{"project" : "atlas"} --> {"project" : { "stringValue": "atlas"}}

Good call. Added auto-normalization — plain strings are now auto-wrapped:

{"project": "atlas"} → {"project": {"stringValue": "atlas"}}

Both forms accepted. Updated the README examples to use the simpler format.

Hweinstock · 2026-03-13T21:14:13Z

src/bedrock_agentcore/memory/integrations/strands/session_manager.py

+RESERVED_METADATA_KEYS = frozenset({STATE_TYPE_KEY, AGENT_ID_KEY})
+
+
+class BufferedMessage(NamedTuple):


nice, I agree with the decision to add some structure here.

Hweinstock · 2026-03-13T21:18:38Z

tests/bedrock_agentcore/memory/integrations/strands/test_agentcore_memory_session_manager.py

+
+    def test_metadata_reserved_keys_rejected(self, session_manager):
+        """ValueError raised when user metadata contains reserved keys."""
+        from bedrock_agentcore.memory.integrations.strands.session_manager import RESERVED_METADATA_KEYS


nit: personally still new to python, but in most languages I'm used to seeing imports at the top unless we have a strong reason not to. lmk if python convention is different.

Moved all inline from datetime import ... to the top of the test file. You're right — top-level is the Python convention too.

Hweinstock · 2026-03-13T21:24:46Z

src/bedrock_agentcore/memory/integrations/strands/config.py

            Default is "user_context".
        filter_restored_tool_context: When True, strip historical toolUse/toolResult blocks from
            restored messages before loading them into Strands runtime memory. Default is False.
+        default_metadata: Optional default metadata key-value pairs to attach to every message event.


are we sure this is the interface the customer is looking for? Could we ask them to send an example code block of the support they want?

Hweinstock · 2026-03-13T21:26:22Z

src/bedrock_agentcore/memory/integrations/strands/config.py

    flush_interval_seconds: Optional[float] = Field(default=None, gt=0)
    context_tag: str = Field(default="user_context", min_length=1)
    filter_restored_tool_context: bool = Field(default=False)
+    default_metadata: Optional[Dict[str, Any]] = None


Is there a reason we need Any here instead of the MetadataValue used internally?

Tried switching to MetadataValue (a TypedDict) but Pydantic on Python < 3.12 rejects TypedDict from typing in model fields. Kept Any in the type annotation but added a field_validator that normalizes plain strings at config construction time, and normalize_metadata() at runtime for metadata_provider output. So the internal plumbing always gets the right shape regardless of what the user passes.

Hweinstock · 2026-03-13T21:29:28Z

src/bedrock_agentcore/memory/integrations/strands/README.md

+with `default_metadata` and `metadata_provider` (per-call values override both for the same key):
+
+```python
+session_manager.create_message(


what happens when we flush messages in a batch and the metadata is different on each message? Does all the metadata get merged?

When messages in a batch have different metadata, the metadata dicts are merged (later message's keys override earlier ones for the same key). So with batch_size > 1, the last value for each key wins in the combined event. This is documented in the batching tradeoff — with batch_size=1 (the default) each turn gets its own event with its own metadata, so no merging occurs.

- Auto-normalize plain string metadata values to {"stringValue": ...} so users can write {"project": "atlas"} instead of the verbose form. Applied via pydantic validator on default_metadata and at runtime for metadata_provider return values. - Move inline datetime imports to top of test file (nit from Hweinstock) - Fix lint/format issues that caused CI Lint and Format check to fail - Add tests for normalization in both config and session manager

Hweinstock

LGTM! probably worth getting a quick review from @jariy17 as well since he is more knowledgable here.

src/bedrock_agentcore/memory/integrations/strands/config.py

src/bedrock_agentcore/memory/integrations/strands/session_manager.py

Pydantic v2 handles Callable natively, so arbitrary_types_allowed is not needed. Removing it avoids any risk of breaking subclasses or downstream validators.

tejaskash requested a review from a team March 13, 2026 20:48

tejaskash temporarily deployed to auto-approve March 13, 2026 20:48 — with GitHub Actions Inactive

jariy17 reviewed Mar 13, 2026

View reviewed changes

tejaskash temporarily deployed to auto-approve March 13, 2026 21:23 — with GitHub Actions Inactive

Hweinstock reviewed Mar 13, 2026

View reviewed changes

tejaskash mentioned this pull request Mar 14, 2026

feat(strands-memory): add multi-agent support to AgentCoreMemorySessionManager #342

Closed

5 tasks

tejaskash temporarily deployed to auto-approve March 16, 2026 18:06 — with GitHub Actions Inactive

Hweinstock previously approved these changes Mar 16, 2026

View reviewed changes

jariy17 previously approved these changes Mar 16, 2026

View reviewed changes

src/bedrock_agentcore/memory/integrations/strands/config.py Outdated Show resolved Hide resolved

src/bedrock_agentcore/memory/integrations/strands/session_manager.py Show resolved Hide resolved

fix: remove unnecessary model_config from AgentCoreMemoryConfig

4fabb95

Pydantic v2 handles Callable natively, so arbitrary_types_allowed is not needed. Removing it avoids any risk of breaking subclasses or downstream validators.

tejaskash dismissed stale reviews from jariy17 and Hweinstock via 4fabb95 March 16, 2026 19:16

tejaskash temporarily deployed to auto-approve March 16, 2026 19:17 — with GitHub Actions Inactive

jariy17 approved these changes Mar 16, 2026

View reviewed changes

tejaskash merged commit cd2f2a0 into main Mar 16, 2026
23 checks passed

jariy17 deleted the worktree-pr1-metadata-support branch March 16, 2026 21:15

		RESERVED_METADATA_KEYS = frozenset({STATE_TYPE_KEY, AGENT_ID_KEY})


		class BufferedMessage(NamedTuple):

Conversation

tejaskash commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage example (Langfuse traceId)

Test plan

Related

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Hweinstock left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tejaskash commented Mar 13, 2026 •

edited

Loading