Conversation State
Conversation state tracks the history of messages and actions within a single conversation or user session. It gives the agent context for understanding follow-up requests.
What Is Conversation State?
When a user interacts with an agent over multiple messages, the agent needs to remember what was said earlier in the conversation.
Conversation state includes:
- All previous user messages
- All previous agent responses
- Any tool calls made during the conversation
- Any context or preferences the user expressed earlier
Example:
User: 'Search for the latest news on AI.'
Agent: Searches and returns 5 articles.
User: 'Summarise the third one.'
Without conversation state, the agent does not know what 'the third one' refers to. With conversation state, it can look back and find the third article from the search results.
Conversation State Structure
# Conversation state for a multi-turn agent
class ConversationState:
def __init__(self, session_id: str, user_id: str):
self.session_id = session_id
self.user_id = user_id
self.messages = [] # Full conversation history
self.context = {} # Extracted context (preferences, entities mentioned)
self.last_results = {} # Results from recent tool calls
def add_user_message(self, content: str):
self.messages.append({
"role": "user",
"content": content,
"timestamp": "now"
})
def add_agent_response(self, content: str, tool_calls: list = None):
self.messages.append({
"role": "assistant",
"content": content,
"tool_calls": tool_calls or [],
"timestamp": "now"
})
def store_result(self, key: str, value):
"""Store tool results for reference in follow-up messages."""
self.last_results[key] = value
def get_recent_history(self, turns: int = 5) -> list:
"""Return the last N turns (each turn = 1 user + 1 agent message)."""
return self.messages[-(turns * 2):]
def set_context(self, key: str, value):
"""Store user preferences or entities for the session."""
self.context[key] = value
conv = ConversationState("SESS-001", "USER-123")
conv.add_user_message("Find the top 3 Python frameworks")
conv.store_result("search_results", ["Django", "FastAPI", "Flask"])
conv.add_agent_response("I found Django, FastAPI, and Flask.")
conv.add_user_message("Tell me more about the second one")
# Agent can now resolve 'second one' from last_results["search_results"][1]
print("Second framework:", conv.last_results["search_results"][1])