Add Session Memory

[knowsuchagency]

Please read this first

• Have you read the docs?Agents SDK docs
  • yes
• Have you searched for related issues? Others may have had similar requests
  • yes

Describe the feature

I've noticed it greatly improves developer experience to have an interface with a default implementation (or two) to handle conversation memory.

The docs suggest the following to handle memory:

async def main():
    agent = Agent(name="Assistant", instructions="Reply very concisely.")

    with trace(workflow_name="Conversation", group_id=thread_id):
        # First turn
        result = await Runner.run(agent, "What city is the Golden Gate Bridge in?")
        print(result.final_output)
        # San Francisco

        # Second turn
        new_input = result.to_input_list() + [{"role": "user", "content": "What state is it in?"}]
        result = await Runner.run(agent, new_input)
        print(result.final_output)
        # California

It's currently left to the user to explicitly manage session memory using result.to_input_list()

Alternatives

A good example of what this could look like is Google's ADK.

Another such example from my own AI abstraction library, Promptic

[rm-openai]

Yeah fair feedback. Would love to discuss the interface in this issue and would even welcome a contribution once we are happy with it!

[knowsuchagency]

Cool! I went ahead and submitted #752 after some experimentation. I'm more than happy to workshop the API -- I just found coding and documentation to be the best way to shape my thinking.

Usage

from agents import Agent, Runner, Session, SQLiteSession

agent = Agent(name="Assistant", instructions="Reply concisely.")
session: Session = SQLiteSession("convo_123")

messages = [
    "Hi, I'm planning a trip to Japan",
    "What's the best time to visit?",
    "How about cherry blossom season?"
]

for message in messages:
    response = Runner.run_sync(agent, message, session=session)
    print(response.final_output)

Session Interface

The basic idea is to have an interface (typing.Protocol) that describes how to manage conversation history for a given session. A Session instance would be passed to one of the Runner methods to handle conversation history for the session. I included a SQLiteSession implementation since that won't introduce any new dependencies.

class CustomSession:
    session_id: str

    async def get_messages(self, limit: int | None = None) -> List[dict]:
        ...
    async def add_messages(self, messages: List[dict]) -> None:
        ...
    async def pop_message(self) -> dict | None:
        ...
    async def clear_session(self) -> None:
        ...