Conversation API

Types and utilities for working with conversation history.

ToolCallInfo

Information about a tool call in the conversation.

zap_ai.ToolCallInfo dataclass

Information about a tool call in the conversation.

Attributes:

Name	Type	Description
id	str	Unique identifier for this tool call.
name	str	Name of the tool that was called.
arguments	dict[str, Any]	Parsed arguments dict passed to the tool.
result	str | None	The tool's result, if available.

Source code in src/zap_ai/conversation/models.py

@dataclass
class ToolCallInfo:
    """
    Information about a tool call in the conversation.

    Attributes:
        id: Unique identifier for this tool call.
        name: Name of the tool that was called.
        arguments: Parsed arguments dict passed to the tool.
        result: The tool's result, if available.
    """

    id: str
    name: str
    arguments: dict[str, Any]
    result: str | None = None

ConversationTurn

A single turn in the conversation.

zap_ai.ConversationTurn dataclass

A single turn in the conversation.

A turn consists of a user message (or system prompt for turn 0), followed by all assistant responses and tool interactions until the next user message.

Attributes:

Name	Type	Description
turn_number	int	Zero-indexed turn number.
user_message	dict[str, Any] | None	The user (or system) message that started this turn.
assistant_messages	list[dict[str, Any]]	All assistant responses in this turn.
tool_messages	list[dict[str, Any]]	All tool result messages in this turn.

Source code in src/zap_ai/conversation/models.py

@dataclass
class ConversationTurn:
    """
    A single turn in the conversation.

    A turn consists of a user message (or system prompt for turn 0),
    followed by all assistant responses and tool interactions until
    the next user message.

    Attributes:
        turn_number: Zero-indexed turn number.
        user_message: The user (or system) message that started this turn.
        assistant_messages: All assistant responses in this turn.
        tool_messages: All tool result messages in this turn.
    """

    turn_number: int
    user_message: dict[str, Any] | None = None
    assistant_messages: list[dict[str, Any]] = field(default_factory=list)
    tool_messages: list[dict[str, Any]] = field(default_factory=list)

Usage Example

from zap_ai import Zap, ToolCallInfo, ConversationTurn

# After task completion
task = await zap.get_task(task_id)

# Get all tool calls
tool_calls: list[ToolCallInfo] = task.get_tool_calls()
for tc in tool_calls:
    print(f"Called {tc.name} with {tc.arguments}")
    print(f"Result: {tc.result}")

# Navigate by turns
turns: list[ConversationTurn] = task.get_turns()
for turn in turns:
    print(f"Turn {turn.turn_number}:")
    if turn.user_message:
        print(f"  User: {turn.user_message.get('content')}")
    for msg in turn.assistant_messages:
        if msg.get("content"):
            print(f"  Assistant: {msg['content']}")