ToolContext
Provide runtime context to every tool execution.
Usage
ToolContext()When a tool is invoked, Talk Box creates a ToolContext and passes it as the first positional argument. The context carries conversation history, user metadata, and a reference to the ToolRegistry, giving the tool everything it needs to make informed decisions without accepting extra parameters from the caller.
Parameters
conversation_id: Optional[str] = None-
Identifier for the current conversation. Useful for correlating tool calls with conversation logs.
user_id: Optional[str] = None-
Identifier for the user who triggered the tool call.
session_id: Optional[str] = None-
Identifier for the broader session (may span multiple conversations).
conversation_history: Optional[List[Dict[str, Any]]] = None-
List of message dictionaries from the current conversation. Each dictionary contains at minimum
"role"and"content"keys. user_metadata: Optional[Dict[str, Any]] = None-
Arbitrary metadata about the user (preferences, permissions, etc.).
tool_registry: Optional["ToolRegistry"] = None-
The
ToolRegistryinstance that the tool belongs to. Allows tools to discover and invoke other tools at runtime. extra: Optional[Dict[str, Any]] = None- Open-ended dictionary for passing additional data that does not fit the other fields.
Examples
Create a context manually (most often done by ToolEnabledConversation):
from talk_box.tools import ToolContext
ctx = ToolContext(
conversation_id="conv-42",
user_id="user-7",
conversation_history=[
{"role": "user", "content": "What's the weather?"}
],
)
ctx.get_last_messages(1)Attributes
| Name | Description |
|---|---|
| timestamp | Alias for created_at for backward compatibility. |
timestamp
Alias for created_at for backward compatibility.
timestamp: datetime
Methods
| Name | Description |
|---|---|
| create_child_context() | Create a child context with some values overridden. |
| get_last_messages() | Get the last N messages from conversation history. |
| get_user_preference() | Get a user preference from metadata. |
| log_tool_usage() | Log tool usage for analytics. |
create_child_context()
Create a child context with some values overridden.
Usage
create_child_context(**overrides)get_last_messages()
Get the last N messages from conversation history.
Usage
get_last_messages(n=5)get_user_preference()
Get a user preference from metadata.
Usage
get_user_preference(key, default=None)log_tool_usage()
Log tool usage for analytics.
Usage
log_tool_usage(tool_name, parameters)