Conversation Management

AA Kit provides powerful conversation management features that make it easy to build stateful, context-aware interactions with your agents.

New in v0.2.0

Conversation management is now built into AA Kit! Use context managers for automatic session handling, interactive mode for terminal chats, and save/load conversations for analysis.

Key Features

Context Management

Automatic session and context handling with conversation managers

Interactive Mode

Built-in REPL for terminal-based conversations

Save & Load

Export conversations as JSON for analysis or replay

History Tracking

Full conversation history with timestamps

Usage Examples

Basic Conversation with Context

Use a context manager to maintain conversation state

from aakit import Agent

# Create an agent with memory
agent = Agent(
    name="assistant",
    instruction="You are a helpful AI assistant",
    model="gpt-4",
    memory="memory://"  # Enable memory for context
)

# Have a conversation with automatic context management
with agent.conversation() as chat:
    # First message
    response1 = chat.send("My name is Alice")
    print(f"Bot: {response1}")
    
    # Second message - bot remembers the context!
    response2 = chat.send("What's my name?")
    print(f"Bot: {response2}")  # Will remember "Alice"
    
    # Save the conversation
    chat.save("alice_conversation.json")

Interactive Terminal Chat

Start a REPL-like interactive conversation

from aakit import Agent

agent = Agent(
    name="chatbot",
    instruction="You are a friendly chatbot",
    model="gpt-4",
    memory="memory://"
)

# Start interactive mode
agent.interactive()

# This opens an interactive terminal with commands:
# - 'exit' to quit
# - 'clear' to clear history
# - 'save' to save conversation
# - 'history' to view all messages

Multiple Parallel Conversations

Manage multiple conversations with separate contexts

from aakit import Agent

agent = Agent(
    name="multi_assistant",
    instruction="You help with various topics",
    model="gpt-4",
    memory="memory://"
)

# Run two separate conversations
with agent.conversation(title="Tech Support") as tech:
    with agent.conversation(title="Cooking Help") as cook:
        # Tech conversation
        tech_response = tech.send("My computer is slow")
        print(f"Tech: {tech_response}")
        
        # Cooking conversation  
        cook_response = cook.send("How do I make pasta?")
        print(f"Cook: {cook_response}")
        
        # Back to tech - remembers context
        tech_response2 = tech.send("I have 4GB RAM")
        print(f"Tech: {tech_response2}")
        
        # Save both conversations
        tech.save("tech_support.json")
        cook.save("cooking_help.json")

Async Conversation with Streaming

Use async conversations for concurrent operations

import asyncio
from aakit import Agent

async def main():
    agent = Agent(
        name="story_teller",
        instruction="You tell engaging stories",
        model="gpt-4",
        memory="memory://"
    )
    
    async with agent.aconversation() as chat:
        # Regular async message
        response = await chat.send("Tell me about robots")
        print(f"Bot: {response}")
        
        # Stream a response
        print("Bot: ", end="", flush=True)
        async for chunk in chat.stream("Continue the story"):
            print(chunk, end="", flush=True)
        print()

asyncio.run(main())

Conversation History & Management

Access and manage conversation history

from aakit import Agent

agent = Agent("assistant", "You are helpful", "gpt-4", memory="memory://")

with agent.conversation() as chat:
    # Have a conversation
    chat.send("Hello!")
    chat.send("What's the weather like?")
    chat.send("Thanks!")
    
    # Access conversation history
    history = chat.history()
    for msg in history:
        print(f"{msg['role']}: {msg['content']}")
        print(f"  Timestamp: {msg['timestamp']}")
    
    # Clear history if needed
    chat.clear()
    
    # Start fresh
    chat.send("New conversation!")

Simple vs Conversation Mode

Understanding when to use each approach

from aakit import Agent

agent = Agent("assistant", "You are helpful", "gpt-4", memory="memory://")

# Method 1: Simple one-off chats (no context between calls)
response1 = agent.chat("Hello")
response2 = agent.chat("What did I just say?")  # Won't remember

# Method 2: Conversation with context
with agent.conversation() as chat:
    r1 = chat.send("Hello") 
    r2 = chat.send("What did I just say?")  # Will remember!

# Method 3: Manual session management
session_id = "user_123"
r1 = agent.chat("Hello", session_id=session_id)
r2 = agent.chat("What did I just say?", session_id=session_id)  # Will remember

API Reference

Conversation Methods

agent.conversation(session_id=None, title=None)

Returns a conversation context manager for synchronous usage

agent.aconversation(session_id=None, title=None)

Returns an async conversation context manager

agent.interactive(title=None)

Starts an interactive terminal chat session

Conversation Object Methods

chat.send(message)

Send a message and get a response

chat.stream(message)

Stream a response (async only)

chat.history()

Get the full conversation history with timestamps

chat.clear()

Clear the conversation history

chat.save(path=None)

Save the conversation to a JSON file

Best Practices

Use Context Managers

Always use with agent.conversation() for automatic session management and proper cleanup.

Enable Memory

Set memory="memory://" or use a persistent backend like Redis for conversations that maintain context.

Save Important Conversations

Use chat.save() to export conversations for analysis, debugging, or compliance.