Agent Loop¶

当 BumblehiveRuntime 不能满足组合需求时，再使用底层 Agent API。

接口	适合场景
`AgentLoop`	自己组合 Context、Skills、Tools 和 Provider
`ToolCallingRunner`	已经准备好消息，只需要模型与工具循环
`ContextBuilder`	自定义运行上下文
`MessageHistory`	调用者管理的对话历史

skill_names 与 tool_names 都支持三种选择：None 表示全部，[] 表示不提供，非空列表表示只选择指定项。Skill 只把摘要加入上下文，Tool 才是模型可以调用的函数。完整规则见配置 Runtime。

公开接口¶

Public agent-loop composition interfaces.

AgentLoop ¶

Build turn context, then delegate model/tool execution.

run_turn `async` ¶

run_turn(current_user_message: UserMessage, *, provider: ModelProvider, model: str, history: MessageHistory | None = None, history_messages: list[Message] | None = None, generation: GenerationConfig | None = None, workspace: Path | str | None = None, path_allowlist: PathAllowlist = PathAllowlist(), timezone: str | None = None, dynamic_context: Mapping[str, DynamicValue] | None = None, skill_names: list[str] | None = None, tool_names: list[str] | None = None, context_window_tokens: int | None = None, max_tool_result_chars: int | None = None, max_iterations: int | None = None, agent_instructions: str | None = None, hooks: HookInput = None, run_id: str | None = None, session_id: str | None = None, stream: bool = False, checkpoint_callback: CheckpointCallback | None = None) -> AgentRunResult

Run one user turn with optional skill and tool filtering.

skill_names and tool_names use the same selection semantics: None exposes everything, [] exposes nothing, and a non-empty list exposes only the named items in the given order.

history is caller-owned local memory that is read and updated for this call without being retained by the loop. history_messages is a managed-session snapshot and therefore requires session_id.

AgentRunResult `dataclass` ¶

Outcome of one tool-capable model run.

ContextBuilder ¶

Build model request context from caller-provided capabilities.

build ¶

build(*, current_messages: list[Message], workspace: Path | str | None = None, timezone: str | None = None, dynamic_context: Mapping[str, DynamicValue] | None = None, history: Sequence[Message] | None = None, agent_instructions: str | None = None, available_skills: str = '') -> list[Message]

Build the messages for one model request.

workspace, timezone, and dynamic_context carry per-turn runtime values. When omitted, the builder defaults provide workspace and timezone.

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 after AgentLoop.run_turn or ToolCallingRunner.run when carrying history 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.

ToolCallingRunner ¶

Run the provider/tool-calling loop without product-layer concerns.

run `async` ¶

run(*, provider: ModelProvider, tools: ToolManager, messages: list[Message], model: str, generation: GenerationConfig | None = None, workspace: Path | str | None = None, path_allowlist: PathAllowlist = PathAllowlist(), tool_names: list[str] | None = None, context_window_tokens: int | None = None, max_tool_result_chars: int | None = None, max_iterations: int | None = None, emitter: EventEmitter | None = None, stream: bool = False, checkpoint_callback: CheckpointCallback | None = None) -> AgentRunResult

Run model/tool iterations until a final model response is produced.