消息与会话¶

MessageHistory 管理应用提供的内存历史；持久化通过 Runtime 的 session_id 使用。会话存储内部对象不是公开接口。

常用接口¶

接口	用途
`Message`	模型消息字典，包含角色、内容和可选工具调用信息。
`UserMessage`	Runtime 接受的用户输入类型。
`normalize_user_message`	将用户输入转换成标准消息序列。
`MessageHistory`	Runtime 仅读取传入的历史。用 replace_run_messages(result.messages) 显式更新，避免把 system 和运行上下文重复保存。
`AgentError`	结构化错误的 code、message 和 recoverable 字段。它与直接抛出的 Python 异常需要分别处理。

消息输入¶

模型消息字典，包含角色、内容和可选工具调用信息。

Message `module-attribute` ¶

Message: TypeAlias = dict[str, Any]

Runtime 接受的用户输入类型。

UserMessage `module-attribute` ¶

UserMessage: TypeAlias = str | list[Message]

将用户输入转换成标准消息序列。

normalize_user_message ¶

normalize_user_message(value: UserMessage) -> list[Message]

Normalize one user input into the runtime's internal message list.

对话历史¶

Runtime 仅读取传入的历史。用 replace_run_messages(result.messages) 显式更新，避免把 system 和运行上下文重复保存。

MessageHistory ¶

Mutable conversation history container for library users.

add ¶

add(role: str, content: Any = None, **extra: Any) -> Message

Append one message and return the stored copy.

add_user ¶

add_user(content: Any, **extra: Any) -> Message

Append a user message.

add_assistant ¶

add_assistant(content: Any = None, **extra: Any) -> Message

Append an assistant message.

add_tool ¶

add_tool(tool_call_id: str, content: Any, *, name: str = '', **extra: Any) -> Message

Append a tool result message.

extend ¶

extend(messages: Sequence[Mapping[str, Any]]) -> None

Append messages without keeping caller-owned dictionaries.

replace ¶

replace(messages: Sequence[Mapping[str, Any]]) -> None

Replace with already-clean conversation history.

This stores messages exactly as provided, except for cloning each dictionary. Use replace_run_messages for AgentRunResult.messages because run messages include per-turn system and runtime context.

replace_run_messages ¶

replace_run_messages(messages: Sequence[Mapping[str, Any]]) -> None

Replace history from AgentRunResult.messages.

Drops per-turn system messages and strips runtime context from user messages before storing them. Use this to explicitly carry an AgentRunResult into the next turn.

clear ¶

clear() -> None

Remove all stored messages.

get_history ¶

get_history() -> list[Message]

Return a cloned copy of the raw stored history.

prepare ¶

prepare(*, max_tool_result_chars: int | None = None, missing_tool_result_content: str | None = None) -> list[Message]

Return provider-ready history using per-call preparation options.

错误对象¶

结构化错误的 code、message 和 recoverable 字段。它与直接抛出的 Python 异常需要分别处理。

AgentError `dataclass` ¶

Structured error shared by Bumblehive subsystems.