Memory leak: Agent references not released between turns

[ruskaruma]

Describe the bug

Agent objects accumulate in memory during long-running workflows because RunItem objects hold strong references that are never released.

Debug information

• Agents SDK version: v0.6.4
• Python version: Python 3.12

Repro steps

Run an agent multiple times in a loop. Agent objects accumulate in memory instead of being garbage collected.

In src/agents/run.py (line 774), lists are cleared without releasing agent references:

turn_result.pre_step_items.clear()
turn_result.new_step_items.clear()

The SDK has a release_agent() method for this, but it's never called.

Expected behavior

Memory should stay constant across multiple runs, not grow indefinitely.

[seratch]

Hi, thanks for writing in. The two lines of code you've mentioned intentionally does only clearing the lists and it's not a leak source (see #2014 to learn how and why we implemented this way).

RunItems keep strong refs to agents by design so results can report which agent produced them. If you keep RunResult/RunResultStreaming objects around, agents will stay alive. If you have a certain reason to keep those objects in memory for a long time, you can manually call result.release_agents() (or streaming_result.release_agents()) when you want to drop those refs; if you drop the result objects entirely, GC will clean up normally.

If we improve something here further,

1. we may want to mention this somewhere in the documentation.
2. introduce a new opt-in like auto_release_agents=True to customize the behavior

[ruskaruma]

Thanks for the clarification! I verified with a reproduction script that Agent references ARE correctly released by GC when RunResult objects are dropped. My initial concern was based on the code analysis without accounting for standard GC behavior upon object destruction.

[ruskaruma]

However, I really support your suggestion about introducing an auto_release_agents=True option.
In our use case (and likely many others for production/auditing), we often:

1. Log/store RunResult objects to keep a history of what happened.
2. Maintain a long running processes where accidental accumulation of heavy Agent objects attached to those results can be dangerous.

Having an opt-in auto_release_agents=True would give us "safety by default" for stored history, without needing to manually remember to call release_agents() every time. I agree this probably needs a bit more discussion.

I would be happy to open a separate feature request or PR for this if you agree! Let me know about this whenever it is convinient for you.

[ruskaruma]

@seratch
Following up on the discussion above , I wanted to explicitly tag you to get your thoughts on the auto_release_agents=True idea I mentioned.

Thanks!

[seratch]

Thanks for your interest. We may add the option in the future, but it is not a priority for this project at this moment. So, please hold off working on it.

[github-actions]

This issue is stale because it has been open for 7 days with no activity.

[github-actions]

This issue was closed because it has been inactive for 3 days since being marked as stale.