feat: add ToolOutputTrimmer for smart context management

[jkrish]

Summary

Adds a built-in ToolOutputTrimmer class that implements CallModelInputFilter — a sliding-window filter that surgically trims large tool outputs from older conversation turns while keeping recent turns at full fidelity.

Closes #2467. Related: #177, #1494.

What it does

• Derives turn boundaries from user messages (no explicit turn structure needed)
• Only targets function_call_output items in old turns — preserves user/assistant messages and function_call items
• Resolves tool names via call_id mapping for informative summaries
• Skips trimming when the summary would exceed the original size
• Validates all parameters at construction (recent_turns >= 1, max_output_chars >= 1, preview_chars >= 0)
• Never mutates the original input list

Usage

from agents import RunConfig
from agents.memory import ToolOutputTrimmer

config = RunConfig(
    call_model_input_filter=ToolOutputTrimmer(
        recent_turns=2,
        max_output_chars=500,
        preview_chars=200,
        trimmable_tools={"search", "execute_code"},
    ),
)

Files changed

File	Change
src/agents/memory/tool_output_trimmer.py	New — ToolOutputTrimmer dataclass (170 lines)
src/agents/memory/__init__.py	Export ToolOutputTrimmer
src/agents/__init__.py	Export ToolOutputTrimmer
tests/memory/test_tool_output_trimmer.py	30 tests across 6 test classes

Test plan

• make format — clean
• make lint — clean
• make mypy — 0 new errors
• make tests — 1888 passed, 4 skipped, 0 failures (no regressions)
• 30 dedicated tests covering defaults, validation, boundary detection, trimming behavior, sliding window, and edge cases

[seratch]

Thanks for sharing this idea. I haven't checked in depth yet, but we'll consider this in the next minor version.

[seratch]

can you move this to extensions?

[jkrish]

Done — moved to src/agents/extensions/memory/tool_output_trimmer.py with updated imports and tests. Import path is now from agents.extensions.memory import ToolOutputTrimmer.

[seratch]

I don't think call_model_input_filter is only for memory feature users. So, you can place it just under extensions module.

[jkrish]

Done — moved up to src/agents/extensions/tool_output_trimmer.py. Import path is now:

from agents.extensions import ToolOutputTrimmer