aws / aws/bedrock-agentcore-sdk-python
AgentCoreMemorySessionManager: allow excluding binary content from persisted messages
- Lenguaje dominante
- Python
- Estrellas
- 761
- Forks
- 147
- Merge medio
- 1 d 23 h
- PR fusionados (30 d)
- 7
Descripción
### Summary
When a tool result carries a Bedrock `document` or `image` block, `AgentCoreMemorySessionManager` persists the raw bytes to AgentCore Memory.
For a large document, `CreateEvent` rejects the request with HTTP 413 and the agent's turn is destroyed. There is currently no way to persist the message without its binary payload.
### Reproduction
Agent configured with `AgentCoreMemorySessionManager` (defaults: `persistence_mode=FULL`, `batch_size=1`, `async_mode=False`). A tool returns a `document` block containing a ~16.5 MB PDF. Strands appends the tool-result message, the `MessageAddedEvent` hook persists it, and `CreateEvent` returns 413:
```
File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 631, in create_message
event = self.memory_client.gmdp_client.create_event(**create_event_kwargs)
botocore.exceptions.ClientError: An error occurred (413) when calling the CreateEvent operation:
The above exception was the direct cause of the following exception:
File ".../strands/event_loop/event_loop.py", line 832, in _handle_tool_execution
await agent._append_messages(tool_result_message)
File ".../strands/session/session_manager.py", line 46, in
registry.add_callback(MessageAddedEvent, lambda event: self.append_message(...))
File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 840, in append_message
File ".../bedrock_agentcore/memory/integrations/strands/session_manager.py", line 636, in create_message
raise SessionException(f"Failed to create message: {e}") from e
strands.types.exceptions.SessionException: Failed to create message: An error occurred (413) ...
strands.types.exceptions.EventLoopException: Failed to create message: An error occurred (413) ...
```
The tool call itself succeeded. The failure is in persistence, and it aborts the whole invocation, losing every prior step of the turn.
Observed with `bedrock-agentcore` 1.21.0. A 612 KB document persists fine, so the threshold sits somewhere between that and 16.5 MB. It does not appear to be documented, and 413 is not among the modelled `CreateEvent` errors in the API reference.
### Why the existing configuration does not cover this
| Option | Limitation |
|---|---|
| `persistence_mode=NONE` | All or nothing. Disables session history entirely, which is the reason for using the session manager. |
| `filter_restored_tool_context` | Applies on the read side when restoring messages. The failure is on write. |
| `batch_size`, `flush_interval_seconds` | Batching happens downstream of the oversized payload. |
### Why binary content is not worth persisting
Beyond the size failure, storing the bytes has little upside:
1. Long-term memory extraction cannot use base64 document or image payloads.
2. On restore, replaying the bytes into every subsequent model request is usually undesirable.
3. It writes megabytes per turn for content the caller can re-fetch from its own source of truth.
### Proposed change
A hook applied to each message before `create_event`, so callers can substitute or drop content they do
not want persisted:
```python
AgentCoreMemoryConfig(
memory_id=...,
session_id=...,
actor_id=...,
message_transform=lambda message: ..., # Callable[[Message], Message] | None
)
```
A narrower declarative option would also solve the reported case, and may be easier to land:
```python
AgentCoreMemoryConfig(..., persist_binary_content=False)
```
replacing `document` and `image` blocks (including blocks nested inside a `toolResult`) with a short text placeholder, so the restored history stays structurally valid for a subsequent model request.
Either shape would let callers keep session durability without the SDK deciding what belongs in memory.
Guía de contribución
Línea de trabajo
Empieza en bedrock_agentcore/memory/integrations/strands/session_manager.py, especialmente en append_message y create_message, y rastrea cómo llega AgentCoreMemoryConfig a la persistencia. Decide qué estructura de configuración propuesta es adecuada y, después, verifica que los bloques de documento e imagen, incluidos los anidados en toolResult, ya no provoquen solicitudes CreateEvent demasiado grandes, mientras los mensajes restaurados siguen siendo válidos.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- aws, python
- Área
- api, backend
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 52/100