ChatSession

Multi-turn conversation with persistent history and shared budget. Returned by Runtime.chat() and used as an async context manager.

The methods and properties listed below are part of the v1.0.0 stable surface (stability spec §1.3).

ChatSession

ChatSession

Multi-turn conversational session.

Unlike Session (single goal -> result), ChatSession maintains conversation history across multiple user messages. Each send() is one conversation turn where the agent may use tools before responding.

The LLM sees the full conversation history (subject to context compression) and can use tools across turns. Budget accumulates across the entire chat.

history property

history: list[dict[str, str]]

Return conversation history as a list of role/content dicts.

Only includes user and assistant messages (excludes system, tool).

max_history property

max_history: int | None

Configured non-system message retention limit, or None if unlimited.

Mirrors the constructor's max_history argument. None (default) retains unlimited history; an integer caps non-system messages and triggers trimming inside send().

total_cost_usd property

total_cost_usd: float

Total cost across all send() calls in this session.

total_tokens property

total_tokens: int

Total tokens used across all send() calls in this session.

turn_count property

turn_count: int

Number of completed send() turns in this session.

Incremented at the start of each send(); not affected by seed_history() (the seed is pre-existing history, not a turn this session executed).

send async

send(message: str, *, images: list[str] | None = None) -> ChatResponse

Send a message and get the agent's response.

Delegates to ConversationAgent for the full turn loop, gaining all V2 features: ask_user, lazy tools, diagnostics, fidelity compression, thinking assessment, and rich streaming events.

Parameters:

Name	Type	Description	Default
message	str	The user's message text.	required
images	list[str] | None	Optional list of image inputs (URLs, file paths, or data URIs) to include with this message.	None

Returns:

Type	Description
ChatResponse	ChatResponse with the agent's reply and usage metrics.

stream async

stream(message: str) -> AsyncGenerator[StreamEvent, None]

Stream version of send(). Yields events including the response.

Delegates to ConversationAgent for the full turn loop, gaining all V2 features. Yields StreamEvent objects for LLM chunks, tool results, and the final response. After this generator is exhausted the message history is updated just like send().

seed_history

seed_history(messages: list[Message] | list[dict[str, Any]]) -> None

Inject prior conversation messages into this session's history.

Restores a chat session from external storage — e.g. cold-start a chatbot with a user's previous conversation. Seeded messages are appended after the session's system prompt and before any future send() content. Calling twice extends.

Accepts Message instances (canonical) or dict entries of the form {"role": <str>, "content": <str>} for convenience. Roles user, assistant, tool are accepted and seeded; system entries in the seed are skipped — the session's system prompt is owned by the constructor (system_prompt=...).

Parameters:

Name	Type	Description	Default
messages	list[Message] | list[dict[str, Any]]	Prior conversation history. Each entry must be a Message or a dict with non-empty role and content.	required

Raises:

Type	Description
ValueError	If an entry has an unknown role, an unsupported type, or empty content.

Notes

• Idempotent only by user discipline — calling twice extends.
• Does not increment turn_count (those count turns this session executed, not pre-existing history).
• Mid-stream seeding (after send() has been called) is allowed but may collide with active compression state. The user owns that timing call.
• Emits an EventType.HISTORY_SEEDED trace event with seed message count, role counts, and a content digest.

ChatResponse

Single-turn response yielded by ChatSession.send().

ChatResponse

Bases: BaseModel

Response from a single chat turn.