AgentLoop 与 Runner¶

直接组装底层对象时，需要自行管理 Provider、工具与资源生命周期。普通应用从 Runtime 开始。

常用接口¶

接口	用途
`AgentLoop`	构建上下文、选择 Skills 和 Tools，再驱动运行。
`ToolCallingRunner`	对已经准备好的消息执行模型与工具循环。
`ContextBuilder`	组装指令、动态信息和能力说明。窗口裁剪与工具结果截断的应用配置见上下文指南。

循环与执行¶

构建上下文、选择 Skills 和 Tools，再驱动运行。

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, timezone: str | None = None, dynamic_context: Mapping[str, DynamicValue] | None = None, skill_names: list[str] | None = None, tool_names: list[str] | None = None, approval_handler: ToolApprovalHandler | 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 without being updated or retained by the loop. history_messages is a managed-session snapshot and therefore requires session_id.

对已经准备好的消息执行模型与工具循环。

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, tool_names: list[str] | None = None, approval_handler: ToolApprovalHandler | 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.

上下文组装¶

组装指令、动态信息和能力说明。窗口裁剪与工具结果截断的应用配置见上下文指南。

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.