History API Reference

Complete reference for Thread, Message, and Context operations.

Thread Operations

create_thread

Creates a new conversation thread and sets it as the active thread.

thread_id = history.create_thread(metadata={
    "user_id": "alice",
    "topic": "customer_support",
    "tags": ["billing", "urgent"]
})

Parameters

Name	Type	Default	Description
`metadata`	`Optional[Dict]`	`None`	Dictionary of custom metadata to attach to the thread.

Returns

str: The unique ID of the created thread.

use_thread

Switches the active context to an existing thread.

history.use_thread("thread-123-abc")

Parameters

Name	Type	Default	Description
`thread_id`	`str`	-	The ID of the thread to switch to.

get_thread

Retrieves a thread object.

thread = history.get_thread()
print(f"Created: {thread.created_at}")

Parameters

Name	Type	Default	Description
`thread_id`	`Optional[str]`	`None`	The ID of the thread to retrieve. If not provided, returns the current active thread.

Returns

Optional[Thread]: The thread object, or None if not found.

list_threads

Lists all available thread IDs in the storage.

all_threads = history.list_threads()
print(f"Total threads: {len(all_threads)}")

Returns

List[str]: A list of all thread IDs.

delete_thread

Deletes a thread and all its associated messages.

if history.delete_thread(thread_id):
    print("Thread deleted")

Parameters

Name	Type	Default	Description
`thread_id`	`str`	-	The ID of the thread to delete.

Returns

bool: True if the thread was successfully deleted, False otherwise.

Message Operations

add_user_message

Adds a user message to the current thread.

msg = history.add_user_message(
    "What's the weather today?",
    metadata={"source": "web"}
)

Parameters

Name	Type	Default	Description
`content`	`str`	-	The text content of the message.
`metadata`	`Optional[Dict]`	`None`	Custom metadata for the message.

Returns

Message: The created message object.

add_assistant_message

Adds an assistant response to the current thread.

msg = history.add_assistant_message(
    "The weather is sunny.",
    agent="WeatherBot",
    metadata={"model": "gpt-4o"}
)

Parameters

Name	Type	Default	Description
`content`	`Any`	-	The content of the response (string or structured).
`agent`	`Optional[str]`	`None`	Name of the agent that generated the response.
`metadata`	`Optional[Dict]`	`None`	Custom metadata (e.g., tokens used, model name).

Returns

Message: The created message object.

add_tool_message

Adds a tool execution result to the current thread.

msg = history.add_tool_message(
    tool_call={
        "name": "get_weather",
        "output": {"temp": 72}
    },
    agent="WeatherBot"
)

Parameters

Name	Type	Default	Description
`tool_call`	`Dict`	-	Dictionary containing tool execution details (name, args, output).
`agent`	`Optional[str]`	`None`	Name of the agent that called the tool.
`metadata`	`Optional[Dict]`	`None`	Custom metadata (e.g., execution time).

Returns

Message: The created message object.

get_messages

Retrieves messages from a thread with optional filtering.

# Get only user messages
user_messages = history.get_messages(role="user")

Parameters

Name	Type	Default	Description
`thread_id`	`Optional[str]`	`None`	Target thread ID. Defaults to current thread.
`role`	`Optional[str]`	`None`	Filter by role ("user", "assistant", "tool", "system").
`agent`	`Optional[str]`	`None`	Filter by agent name.

Returns

List[Message]: List of matching message objects.

get_message_count

Gets the total number of messages in a thread.

count = history.get_message_count()

Parameters

Name	Type	Default	Description
`thread_id`	`Optional[str]`	`None`	Target thread ID. Defaults to current thread.

Returns

int: The number of messages.

delete_message

Deletes a specific message by its ID.

history.delete_message(message_id)

Parameters

Name	Type	Default	Description
`message_id`	`str`	-	The ID of the message to delete.
`thread_id`	`Optional[str]`	`None`	Target thread ID. Defaults to current thread.

Returns

bool: True if deleted successfully.

delete_messages

Deletes multiple messages at once.

history.delete_messages([msg_id_1, msg_id_2])

Parameters

Name	Type	Default	Description
`message_ids`	`List[str]`	-	List of message IDs to delete.
`thread_id`	`Optional[str]`	`None`	Target thread ID. Defaults to current thread.

Returns

int: The number of messages actually deleted.

Context Management Operations

trim_messages

Trims messages to manage context window size.

# Keep only the last 10 messages
history.trim_messages(strategy="last", count=10)

Parameters

Name	Type	Default	Description
`strategy`	`str`	`"last"`	Strategy: `"last"` (keep recent), `"first"` (keep oldest), `"first_last"`.
`count`	`int`	`10`	Number of messages to keep.
`keep_system`	`bool`	`True`	If `True`, system messages are never deleted.
`thread_id`	`Optional[str]`	`None`	Target thread ID.

Returns

int: Number of messages removed.

summarize_messages

Summarizes a range of messages using an LLM and replaces them with a summary.

history.summarize_messages(
    model=groq("llama-3.1-8b-instant"),
    keep_recent=5
)

Parameters

Name	Type	Default	Description
`model`	`Any`	-	LLM model instance for generating summary.
`start_index`	`int`	`0`	Start index for summarization.
`end_index`	`Optional[int]`	`None`	End index (defaults to `len - keep_recent`).
`keep_recent`	`int`	`5`	Number of recent messages to exclude from summary.
`thread_id`	`Optional[str]`	`None`	Target thread ID.

Returns

Message: The newly created summary message.

manage_context_window

Automatically manages context window when messages exceed a threshold.

history.manage_context_window(
    model=groq("llama-3.1-8b-instant"),
    max_messages=20,
    strategy="smart"
)

Parameters

Name	Type	Default	Description
`model`	`Any`	-	LLM model (required for "summarize" and "smart").
`max_messages`	`int`	`20`	Threshold to trigger management.
`strategy`	`str`	`"smart"`	Strategy: `"smart"`, `"trim_last"`, `"trim_first"`, `"summarize"`.
`thread_id`	`Optional[str]`	`None`	Target thread ID.

Data Models

Message Object

Represents a single message in the conversation history.

Property	Type	Description
`id`	`str`	Unique UUID for the message.
`timestamp`	`datetime`	Time when the message was created.
`role`	`str`	Role of the sender (`user`, `assistant`, `tool`, `system`).
`content`	`Any`	The content of the message.
`agent`	`Optional[str]`	Name of the agent (for assistant messages).
`tool_call`	`Optional[Dict]`	Tool execution details (for tool messages).
`metadata`	`Dict`	Custom metadata dictionary.

Thread Object

Represents a conversation thread containing multiple messages.

Property	Type	Description
`id`	`str`	Unique UUID for the thread.
`created_at`	`datetime`	Time when the thread was created.
`updated_at`	`datetime`	Time when the thread was last modified.
`metadata`	`Dict`	Custom metadata dictionary.
`messages`	`List[Message]`	List of messages in the thread.

History API Reference

Complete reference for Thread, Message, and Context operations.

On this page