841 lines
36 KiB
Python
841 lines
36 KiB
Python
"""流式 Agent 循环：stream → 累积 tool_calls → execute → 回填 ToolMessage → 再 stream。
|
||
|
||
阶段2b 步骤A：把 Agent 工具调用闭环从非流式 ``router.chat`` 改成流式 ``router.stream``，
|
||
并在主循环中暴露两个可选 async 回调（``on_chunk`` / ``on_tool_event``）供上层（步骤B
|
||
send_message）接入 SSE 增量冲刷与工具事件。本模块不感知 SSE / 前端，回调签名仅约定：
|
||
|
||
- ``on_chunk(chunk: ChatChunk)``：每个流式 chunk 透传（含 delta_content / delta_reasoning
|
||
/ tool_call_chunks / usage 等），上层可据此写 ``message.delta``。
|
||
- ``on_tool_event(event_type: str, payload: dict)``：工具生命周期事件：
|
||
- ``"tool.started"``：执行前
|
||
- ``"tool.completed"``：执行后，含 status（success / error / denied）
|
||
- ``"tool.requires_confirmation"``（阶段3 新增）：高风险工具抛 RequiresConfirmation 时
|
||
发出，带 confirmation_id / risk_level / args，供前端展示确认卡片、approve/deny 端点
|
||
据此恢复循环。
|
||
|
||
阶段3 步骤1：工具确认挂起/恢复机制。
|
||
- 主循环遇到 ``RequiresConfirmation`` 时，通过 ``confirmation_registry.register(cid)`` 取
|
||
一个 ``Future[bool]`` 并 ``await``；外部 approve/deny 端点（步骤2）调
|
||
``registry.resolve(cid, approved)`` 触发恢复。
|
||
- 批准：以 ``confirmed=True`` 重试 execute；拒绝：回填"用户拒绝"ToolMessage，循环继续。
|
||
- 超时：``confirmation_timeout``（默认 300s）未裁决按拒绝处理；该超时受外层
|
||
``run_timeout``（send_message 的 ``asyncio.timeout``）约束——确认必须在 run 超时内完成。
|
||
- ``confirmation_registry`` 为 None 时降级：回填"需确认但未启用"消息，循环不卡（向下兼容）。
|
||
|
||
设计要点：
|
||
- 流式 ``router.stream(...)`` 返回 ``AsyncIterator[ChatChunk]``；流结束（async for 正常
|
||
退出）即本轮模型输出完毕，``ToolCallAccumulator.drain()`` 给出完整 tool_calls——不依赖
|
||
``finish_reason`` 判断。
|
||
- 工具执行经 ``ToolRuntime.execute``——司命评估与事件落库由其内部完成，本层只负责调用与
|
||
错误兜底。
|
||
- 工具失败**不中断循环**：异常被捕获、错误信息以 ToolMessage content 回填，让模型自行决策。
|
||
RequiresConfirmation 单独处理（不走错误兜底分支）。
|
||
- usage 累计每轮 prompt/completion/total_tokens。
|
||
- ``on_chunk`` / ``on_tool_event`` 默认 None；不传时本循环与纯后端逻辑等价。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
from collections.abc import Awaitable, Callable
|
||
from dataclasses import dataclass, field
|
||
from typing import Any
|
||
|
||
from app.ai_provider import ProviderManagerFactory, TokenUsage
|
||
from app.ai_provider.llm import ToolCallAccumulator
|
||
from app.ai_provider.types.chat import ChatChunk
|
||
from app.ai_provider.types.messages import AIMessage, BaseMessage, ToolMessage
|
||
from app.application.agent.confirmation import ConfirmationRegistry
|
||
from app.application.agent.extensions import (
|
||
AgentContext,
|
||
AgentEvent,
|
||
AgentRunContext,
|
||
CancellationToken,
|
||
ExtensionRegistry,
|
||
ToolCallContext,
|
||
TurnSnapshot,
|
||
)
|
||
from app.core.logging import logger
|
||
from app.models.safety import PendingConfirmationRecord
|
||
from app.modules.safety.confirmation import new_confirmation_id
|
||
from app.modules.safety.exceptions import RequiresConfirmation
|
||
from app.modules.tool_runtime.definition import ToolResult, ToolRuntimeLike
|
||
|
||
# 默认最大循环次数：覆盖常见多步工具调用，超限则截断返回，避免无限循环。
|
||
DEFAULT_MAX_ITERATIONS = 8
|
||
|
||
# 默认确认超时：高风险工具挂起等待用户裁决的最长时间（秒）；超时按拒绝处理。
|
||
DEFAULT_CONFIRMATION_TIMEOUT = 300.0
|
||
|
||
# 回调类型别名：给上层（步骤B send_message）类型检查用
|
||
OnChunkCallback = Callable[[ChatChunk], Awaitable[None]]
|
||
OnToolEventCallback = Callable[[str, dict[str, Any]], Awaitable[None]]
|
||
|
||
|
||
@dataclass
|
||
class AgentTurnResult:
|
||
"""单轮 Agent 循环的产出。"""
|
||
|
||
content: str # 最终回复正文（最后一次模型输出）
|
||
reasoning: str # 最终回复的思考内容（如有）
|
||
tool_history: list[dict[str, Any]] = field(
|
||
default_factory=list
|
||
) # [{name, args, result, status, tool_call_id?}]
|
||
iterations: int = 0 # 实际循环次数
|
||
truncated: bool = False # 是否因达上限截断
|
||
usage: TokenUsage = field(default_factory=TokenUsage) # 累计 token 用量
|
||
|
||
|
||
def _sum_usage(acc: TokenUsage, delta: TokenUsage) -> TokenUsage:
|
||
return acc + delta
|
||
|
||
|
||
def _parse_tool_args(args_str: str) -> dict[str, Any]:
|
||
"""把累积到的 args JSON 字符串解析成 dict；解析失败时回退 ``{"_raw": ...}``。"""
|
||
if not args_str:
|
||
return {}
|
||
try:
|
||
parsed = json.loads(args_str)
|
||
except json.JSONDecodeError:
|
||
return {"_raw": args_str}
|
||
if isinstance(parsed, dict):
|
||
return parsed
|
||
# 非对象 JSON（数组/字符串/数字）——包成 _raw 让模型自己理解
|
||
return {"_raw": args_str}
|
||
|
||
|
||
def _ai_message_from_stream(
|
||
content: str,
|
||
reasoning: str,
|
||
tool_calls: list[dict[str, Any]],
|
||
raw_content_blocks: list[dict[str, Any]] | None = None,
|
||
) -> AIMessage:
|
||
"""把流式累积的 content/reasoning/tool_calls 还原成 AIMessage 以便追加到 messages 历史。
|
||
|
||
``tool_calls`` 元素结构为 ``{"index", "id"?, "name"?, "args": str}``（由
|
||
``ToolCallAccumulator.drain`` 产出，``args`` 为完整 JSON 字符串）。AIMessage 期望
|
||
``{"name": ..., "args": dict, "id": ...}``，故需反序列化 args 并补全缺失 id。
|
||
"""
|
||
lc_tool_calls: list[dict[str, Any]] = []
|
||
for entry in tool_calls:
|
||
name = entry.get("name")
|
||
if not name:
|
||
# 没有 name 的 tool_call 无法执行，跳过（保留在累积器视图但不进历史）
|
||
continue
|
||
tc_id = entry.get("id") or f"call_{name}"
|
||
lc_tool_calls.append(
|
||
{
|
||
"name": name,
|
||
"args": _parse_tool_args(entry.get("args", "")),
|
||
"id": tc_id,
|
||
}
|
||
)
|
||
return AIMessage(
|
||
content=content,
|
||
tool_calls=lc_tool_calls,
|
||
reasoning=reasoning,
|
||
raw_content_blocks=raw_content_blocks,
|
||
)
|
||
|
||
|
||
def _truncate(text: str, limit: int = 4000) -> str:
|
||
"""截断超长文本（沙箱 stdout/stderr 可能很大），避免喂回模型时爆 token。
|
||
|
||
措辞明确这是「回显截断」而非数据损坏，并告知取后续内容的方法：否则模型读到大文件
|
||
被 read_file 截断的结果，会反复换方法重读，陷入循环直到 ``max_iterations`` 截断。
|
||
阈值 4000 兼顾 token 成本与单次可读量；大文件配合 read_file 的 offset/limit 分段读取。
|
||
"""
|
||
if len(text) <= limit:
|
||
return text
|
||
return (
|
||
f"{text[:limit]}\n…[输出过长，仅回显前 {limit} 字符；原始内容完整。"
|
||
f"如需后续内容：read_file 用 offset/limit 分段，或 shell 用 sed -n / tail / head 限定输出]"
|
||
)
|
||
|
||
|
||
async def _publish_message_lifecycle(
|
||
registry: ExtensionRegistry,
|
||
run: AgentRunContext,
|
||
message: BaseMessage,
|
||
) -> None:
|
||
"""发布一条完整消息的 start/end 生命周期。"""
|
||
if not registry.enabled:
|
||
return
|
||
payload = {"role": message.role, "message": message.to_dict()}
|
||
await registry.publish(AgentEvent("message.started", payload), run)
|
||
await registry.publish(AgentEvent("message.ended", payload), run)
|
||
|
||
|
||
def _tool_result_text(result: ToolResult) -> str:
|
||
"""把 ToolResult 转成回填给模型的紧凑文本。
|
||
|
||
显式标注 ``status=成功/失败``：否则成功路径（如 write_file 落盘后 stdout/stderr 全空）
|
||
只剩孤零零的 ``exit_code=0``，模型缺乏「已成功」的明确语义，倾向再调 read_file 验证，
|
||
叠加回显截断极易陷入反复重试。
|
||
"""
|
||
status = "成功" if result.ok else "失败"
|
||
parts = [f"status={status} exit_code={result.exit_code}"]
|
||
if result.stdout:
|
||
parts.append(f"stdout:\n{_truncate(result.stdout)}")
|
||
if result.stderr:
|
||
parts.append(f"stderr:\n{_truncate(result.stderr)}")
|
||
if result.timeout:
|
||
parts.append("timeout=true")
|
||
if result.truncated:
|
||
parts.append("truncated=true（仅截断回显给模型的输出，不影响已落盘等实际副作用）")
|
||
return "\n".join(parts)
|
||
|
||
|
||
# 控制流哨兵异常：只在本模块内传递，不泄漏到 run_agent_turn 调用方。
|
||
class _ToolDenied(Exception):
|
||
"""用户拒绝 / 确认超时。``message`` 为回填文本，``reason`` 为内部归因（denied/timeout）。"""
|
||
|
||
def __init__(self, message: str, *, reason: str = "denied") -> None:
|
||
super().__init__(message)
|
||
self.message = message
|
||
self.reason = reason
|
||
|
||
|
||
class _ToolSkipped(Exception):
|
||
"""confirmation_registry 未启用时的降级：回填"需确认但未启用"消息。"""
|
||
|
||
def __init__(self, message: str) -> None:
|
||
super().__init__(message)
|
||
self.message = message
|
||
|
||
|
||
async def _execute_tool_with_confirmation(
|
||
*,
|
||
tool_runtime: ToolRuntimeLike | None,
|
||
name: str,
|
||
tool_input: dict[str, Any],
|
||
args_str: str,
|
||
tool_call_id: str,
|
||
run_id: str | None,
|
||
character_id: str | None,
|
||
trace_id: str | None,
|
||
base_confirmed: bool,
|
||
confirmation_registry: ConfirmationRegistry | None,
|
||
confirmation_timeout: float,
|
||
on_tool_event: OnToolEventCallback | None,
|
||
cancellation: CancellationToken | None = None,
|
||
on_timeout: Callable[[str], Awaitable[None]] | None = None,
|
||
) -> ToolResult:
|
||
"""执行单次工具调用，处理 RequiresConfirmation 挂起/恢复。
|
||
|
||
- 正常返回 ToolResult；任意终态（拒绝/超时/降级）以本模块哨兵异常向调用方信号。
|
||
- 批准路径以 ``confirmed=True`` 重试 execute（绕过司命 ask），失败仍正常返回 ToolResult
|
||
（由调用方按 ok=False 回填 error 文本）。
|
||
- ``on_timeout(confirmation_id)``：确认超时时回调，供调用方标记超时。
|
||
"""
|
||
# base_confirmed=True 表示调用方已保证确认（如 API 已先确认），直接执行
|
||
use_confirmed = base_confirmed
|
||
if tool_runtime is None:
|
||
raise _ToolSkipped("工具运行时未启用，已跳过工具调用。")
|
||
|
||
while True:
|
||
try:
|
||
return await tool_runtime.execute(
|
||
name,
|
||
tool_input,
|
||
run_id=run_id,
|
||
character_id=character_id,
|
||
trace_id=trace_id,
|
||
confirmed=use_confirmed,
|
||
context={"cancellation": cancellation} if cancellation is not None else None,
|
||
)
|
||
except RequiresConfirmation as exc:
|
||
if use_confirmed:
|
||
raise _ToolSkipped(f"工具 {name} 在已确认状态下仍要求确认，已跳过。") from exc
|
||
|
||
# ---- registry 未启用：降级 ----
|
||
if confirmation_registry is None:
|
||
raise _ToolSkipped(
|
||
f"工具 {name} 需要用户确认（风险等级 {exc.risk_level or 'L2'}），"
|
||
"但当前未启用确认流程，已跳过。"
|
||
) from exc
|
||
|
||
# ---- registry 已启用：登记 + 持久化待确认 + 发事件 + await ----
|
||
confirmation_id = new_confirmation_id()
|
||
|
||
# 先持久化待确认记录（多 worker 共享确认状态），再发事件。
|
||
# 顺序保证：resolve/deny 回调（on_tool_event 触发的 create_task）看到记录时，
|
||
# DB 里已有该行，不会空转超时。
|
||
if run_id:
|
||
from app.db.session import AsyncSessionLocal
|
||
|
||
async with AsyncSessionLocal() as session:
|
||
record = PendingConfirmationRecord(
|
||
id=confirmation_id,
|
||
tool=name,
|
||
input_json=json.dumps(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"tool_call_id": tool_call_id,
|
||
"args_str": args_str,
|
||
}
|
||
),
|
||
risk_level=exc.risk_level or "L2",
|
||
reason=exc.message,
|
||
run_id=run_id,
|
||
character_id=character_id,
|
||
status="pending",
|
||
)
|
||
session.add(record)
|
||
await session.commit()
|
||
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.requires_confirmation",
|
||
{
|
||
"confirmation_id": confirmation_id,
|
||
"run_id": run_id,
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"risk_level": exc.risk_level,
|
||
"reason": exc.message,
|
||
"args": args_str,
|
||
},
|
||
)
|
||
|
||
# 使用混合确认注册表（同进程 Event + 重启后 polling）。无 run_id 的
|
||
# 独立调用仍可等待到超时，避免把“未裁决”误报成“确认机制未启用”。
|
||
confirmation_run_id = run_id or confirmation_id
|
||
try:
|
||
approved = await confirmation_registry.wait(
|
||
confirmation_run_id,
|
||
confirmation_id=confirmation_id,
|
||
timeout=confirmation_timeout,
|
||
)
|
||
except TimeoutError:
|
||
if on_timeout is not None:
|
||
await on_timeout(confirmation_id)
|
||
raise _ToolDenied(
|
||
f"工具 {name} 的确认超时（等待 {confirmation_timeout:.0f}s 未裁决），已按拒绝处理。",
|
||
reason="timeout",
|
||
) from None
|
||
|
||
if not approved:
|
||
raise _ToolDenied(f"用户拒绝了工具 {name} 的执行。") from exc
|
||
|
||
# 批准：以 confirmed=True 重试 execute（循环回到顶部 try）
|
||
logger.info(
|
||
"agent_tool_confirmed",
|
||
tool=name,
|
||
confirmation_id=confirmation_id,
|
||
run_id=run_id,
|
||
)
|
||
use_confirmed = True
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.started",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"args": args_str,
|
||
"confirmed": True,
|
||
},
|
||
)
|
||
|
||
|
||
async def run_agent_turn(
|
||
*,
|
||
messages: list[BaseMessage],
|
||
tools: list[dict[str, Any]],
|
||
tool_runtime: ToolRuntimeLike | None,
|
||
model_hint: str | None = None,
|
||
thinking_enabled: bool | None = None,
|
||
reasoning_effort: str | None = None,
|
||
max_iterations: int = DEFAULT_MAX_ITERATIONS,
|
||
# 可选上下文：透传给 ToolRuntime.execute 做事件归属与工作目录隔离
|
||
run_id: str | None = None,
|
||
character_id: str | None = None,
|
||
trace_id: str | None = None,
|
||
# 可选：高风险工具是否已由上层确认（透传给 ToolRuntime.execute）
|
||
confirmed: bool = False,
|
||
# 可选：每轮开始时回调（供外层重置 per-turn 状态如 reasoning_finalized）
|
||
on_turn: Callable[[], Awaitable[None]] | None = None,
|
||
# 可选回调：把流式 chunk 透传给上层做 SSE 增量冲刷（默认 None 表示不回调）
|
||
on_chunk: OnChunkCallback | None = None,
|
||
# 可选回调：工具生命周期事件（"tool.started" / "tool.completed" /
|
||
# "tool.requires_confirmation"）
|
||
on_tool_event: OnToolEventCallback | None = None,
|
||
# 可选：确认 Future 注册表（阶段3 步骤1）。缺省 None 时遇 RequiresConfirmation 降级。
|
||
confirmation_registry: ConfirmationRegistry | None = None,
|
||
# 可选：单次确认挂起超时（秒），默认 300s；超时按拒绝处理。
|
||
confirmation_timeout: float = DEFAULT_CONFIRMATION_TIMEOUT,
|
||
# 可选：确认超时回调（confirmation_id → None），供调用方标记 DB 超时状态。
|
||
on_confirm_timeout: Callable[[str], Awaitable[None]] | None = None,
|
||
# 受约束扩展 Hook 与本次运行上下文。
|
||
extensions: ExtensionRegistry | None = None,
|
||
run_context: AgentRunContext | None = None,
|
||
# Stateful Agent 的 steering 队列；每轮工具批次完成后消费。
|
||
get_steering_messages: Callable[[], list[BaseMessage]] | None = None,
|
||
) -> AgentTurnResult:
|
||
"""执行一轮带工具调用的 Agent 循环（流式版）。
|
||
|
||
循环逻辑见模块 docstring；返回值始终是 ``AgentTurnResult``，工具失败不抛异常。
|
||
``max_iterations`` 为硬上限：达到上限且模型仍返回 tool_calls 时返回 truncated=True。
|
||
``on_chunk`` / ``on_tool_event`` 缺省 None 时与纯后端逻辑等价。
|
||
``on_confirm_timeout(confirmation_id)``：确认超时时回调，用于标记 DB 记录。
|
||
|
||
确认挂起/恢复（阶段3 步骤1）：``confirmation_registry`` 缺省 None 时，遇
|
||
``RequiresConfirmation`` 走降级路径（回填"需确认但未启用"消息，循环继续）；否则按
|
||
register → 发 ``tool.requires_confirmation`` 事件 → ``await Future``（带超时）→
|
||
批准重试 / 拒绝回填 的流程处理。``confirmation_timeout`` 须小于上层 run_timeout，否则
|
||
run 先超时。
|
||
"""
|
||
if max_iterations < 1:
|
||
raise ValueError("max_iterations 必须 >= 1")
|
||
|
||
manager = ProviderManagerFactory.create()
|
||
extension_registry = extensions or ExtensionRegistry()
|
||
extension_context = run_context or AgentRunContext(
|
||
run_id=run_id,
|
||
character_id=character_id,
|
||
trace_id=trace_id,
|
||
)
|
||
usage = TokenUsage()
|
||
tool_history: list[dict[str, Any]] = []
|
||
iterations = 0
|
||
# 最后一轮累积值（用于 truncated 分支返回 content/reasoning）
|
||
last_content = ""
|
||
last_reasoning = ""
|
||
|
||
while iterations < max_iterations:
|
||
iterations += 1
|
||
if on_turn is not None:
|
||
await on_turn()
|
||
if extension_registry.enabled:
|
||
await extension_registry.publish(
|
||
AgentEvent("agent.turn.started", {"iteration": iterations}),
|
||
extension_context,
|
||
)
|
||
|
||
# ---- 本轮流式消费 ----
|
||
acc = ToolCallAccumulator()
|
||
content_buf = ""
|
||
reasoning_buf = ""
|
||
finish_reason: str | None = None
|
||
raw_blocks: dict[int, dict[str, Any]] = {}
|
||
params: dict[str, object] = {}
|
||
if thinking_enabled is not None:
|
||
params["thinking_enabled"] = thinking_enabled
|
||
if reasoning_effort is not None:
|
||
params["reasoning_effort"] = reasoning_effort
|
||
extension_context.cancellation.raise_if_cancelled()
|
||
request_context = AgentContext(tuple(messages), tuple(tools), model_hint)
|
||
if extension_registry.enabled:
|
||
request_context = await extension_registry.transform_context(
|
||
request_context,
|
||
extension_context,
|
||
)
|
||
if extension_registry.enabled:
|
||
await extension_registry.publish(
|
||
AgentEvent("message.started", {"role": "assistant", "iteration": iterations}),
|
||
extension_context,
|
||
)
|
||
stream = manager.chat_stream(
|
||
list(request_context.messages),
|
||
model_hint=request_context.model_hint,
|
||
params=params,
|
||
tools=list(request_context.tools) or None,
|
||
)
|
||
async for chunk in stream:
|
||
if on_chunk is not None:
|
||
await on_chunk(chunk)
|
||
if extension_registry.enabled and (chunk.delta_content or chunk.delta_reasoning):
|
||
await extension_registry.publish(
|
||
AgentEvent(
|
||
"message.updated",
|
||
{
|
||
"role": "assistant",
|
||
"iteration": iterations,
|
||
"delta": chunk.delta_content,
|
||
"reasoning_delta": chunk.delta_reasoning,
|
||
},
|
||
),
|
||
extension_context,
|
||
)
|
||
if chunk.delta_content:
|
||
content_buf += chunk.delta_content
|
||
if chunk.delta_reasoning:
|
||
reasoning_buf += chunk.delta_reasoning
|
||
if chunk.finish_reason is not None:
|
||
finish_reason = chunk.finish_reason
|
||
if chunk.content_block_start is not None and chunk.content_block_index is not None:
|
||
raw_blocks[chunk.content_block_index] = dict(chunk.content_block_start)
|
||
if chunk.content_block_delta is not None and chunk.content_block_index is not None:
|
||
block = raw_blocks.get(chunk.content_block_index)
|
||
if block is not None:
|
||
delta = chunk.content_block_delta
|
||
delta_type = delta.get("type")
|
||
if delta_type == "text_delta":
|
||
block["text"] = f"{block.get('text', '')}{delta.get('text', '')}"
|
||
elif delta_type == "thinking_delta":
|
||
block["thinking"] = (
|
||
f"{block.get('thinking', '')}{delta.get('thinking', '')}"
|
||
)
|
||
elif delta_type == "signature_delta":
|
||
block["signature"] = (
|
||
f"{block.get('signature', '')}{delta.get('signature', '')}"
|
||
)
|
||
elif delta_type == "input_json_delta":
|
||
block["_partial_json"] = (
|
||
f"{block.get('_partial_json', '')}{delta.get('partial_json', '')}"
|
||
)
|
||
if chunk.usage is not None:
|
||
usage = _sum_usage(usage, chunk.usage)
|
||
acc.add_chunk(chunk)
|
||
|
||
# 流结束即本轮模型输出完毕
|
||
tool_calls = acc.drain()
|
||
last_content = content_buf
|
||
last_reasoning = reasoning_buf
|
||
|
||
raw_content_blocks: list[dict[str, Any]] = []
|
||
for index in sorted(raw_blocks):
|
||
block = raw_blocks[index]
|
||
partial_json = block.pop("_partial_json", None)
|
||
if partial_json is not None:
|
||
block["input"] = _parse_tool_args(partial_json)
|
||
raw_content_blocks.append(block)
|
||
|
||
# 把模型输出（含 thinking signature / tool_calls）原样追加到历史。
|
||
ai_message = _ai_message_from_stream(
|
||
content_buf,
|
||
reasoning_buf,
|
||
tool_calls,
|
||
raw_content_blocks or None,
|
||
)
|
||
messages.append(ai_message)
|
||
if extension_registry.enabled:
|
||
await extension_registry.publish(
|
||
AgentEvent(
|
||
"message.ended",
|
||
{
|
||
"role": "assistant",
|
||
"iteration": iterations,
|
||
"message": ai_message.to_dict(),
|
||
"finish_reason": finish_reason,
|
||
},
|
||
),
|
||
extension_context,
|
||
)
|
||
|
||
# 无工具调用：先消费 steering，再决定是否结束。
|
||
if not any(tc.get("name") for tc in tool_calls):
|
||
steering = get_steering_messages() if get_steering_messages is not None else []
|
||
turn = TurnSnapshot(
|
||
iteration=iterations,
|
||
content=content_buf,
|
||
reasoning=reasoning_buf,
|
||
tool_calls=(),
|
||
tool_results=tuple(tool_history),
|
||
usage=usage,
|
||
)
|
||
if extension_registry.enabled:
|
||
await extension_registry.publish(
|
||
AgentEvent("agent.turn.ended", {"iteration": iterations}),
|
||
extension_context,
|
||
)
|
||
# TurnPolicy 在此分支不参与终止决策：模型无工具调用时已由 steering /
|
||
# finish_reason / 默认 return 收尾，强行接入会覆盖 pause_turn / refusal
|
||
# 既有处理；其真实终止作用在下方工具分支（should_stop or terminate_after_tools）。
|
||
await extension_registry.should_stop(turn, extension_context)
|
||
if steering:
|
||
messages.extend(steering)
|
||
continue
|
||
if finish_reason == "pause_turn":
|
||
continue
|
||
if finish_reason == "refusal":
|
||
raise RuntimeError("模型拒绝了当前请求。")
|
||
return AgentTurnResult(
|
||
content=content_buf,
|
||
reasoning=reasoning_buf,
|
||
tool_history=tool_history,
|
||
iterations=iterations,
|
||
truncated=finish_reason == "length",
|
||
usage=usage,
|
||
)
|
||
|
||
# 逐个执行 tool_call 并把结果以 ToolMessage 回填。工具可能有副作用或需要确认，
|
||
# 在 ToolSpec 未声明并行安全前保持确定性串行执行。
|
||
turn_history_start = len(tool_history)
|
||
terminate_after_tools = False
|
||
for call_index, entry in enumerate(tool_calls):
|
||
name = entry.get("name")
|
||
if not name:
|
||
continue
|
||
args_str = entry.get("args", "")
|
||
tool_input = _parse_tool_args(args_str)
|
||
tool_call_id = entry.get("id") or f"call_{iterations}_{call_index}_{name}"
|
||
hook_call = ToolCallContext(
|
||
tool_call_id=tool_call_id,
|
||
name=name,
|
||
input=tool_input,
|
||
messages=tuple(messages),
|
||
)
|
||
if extension_registry.enabled:
|
||
decision = await extension_registry.before_tool_call(
|
||
hook_call,
|
||
extension_context,
|
||
)
|
||
if not decision.allowed:
|
||
denied_text = decision.reason or f"扩展阻止了工具 {name} 的执行。"
|
||
tool_history.append(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"result": denied_text,
|
||
"status": "denied",
|
||
"tool_call_id": tool_call_id,
|
||
}
|
||
)
|
||
tool_message = ToolMessage(content=denied_text, tool_call_id=tool_call_id)
|
||
messages.append(tool_message)
|
||
await _publish_message_lifecycle(
|
||
extension_registry, extension_context, tool_message
|
||
)
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.completed",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"status": "denied",
|
||
"result": denied_text[:500],
|
||
},
|
||
)
|
||
continue
|
||
if decision.input is not None:
|
||
tool_input = decision.input
|
||
args_str = json.dumps(tool_input, ensure_ascii=False)
|
||
hook_call = ToolCallContext(
|
||
tool_call_id=tool_call_id,
|
||
name=name,
|
||
input=tool_input,
|
||
messages=tuple(messages),
|
||
)
|
||
|
||
# 执行前事件
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.started",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"args": args_str,
|
||
},
|
||
)
|
||
|
||
try:
|
||
tool_result = await _execute_tool_with_confirmation(
|
||
tool_runtime=tool_runtime,
|
||
name=name,
|
||
tool_input=tool_input,
|
||
args_str=args_str,
|
||
tool_call_id=tool_call_id,
|
||
run_id=run_id,
|
||
character_id=character_id,
|
||
trace_id=trace_id,
|
||
base_confirmed=confirmed,
|
||
confirmation_registry=confirmation_registry,
|
||
confirmation_timeout=confirmation_timeout,
|
||
on_tool_event=on_tool_event,
|
||
cancellation=extension_context.cancellation,
|
||
on_timeout=on_confirm_timeout,
|
||
)
|
||
except _ToolDenied as denied:
|
||
# 用户拒绝或确认超时：回填拒绝消息，循环继续让模型自决策
|
||
logger.info(
|
||
"agent_tool_denied",
|
||
tool=name,
|
||
reason=denied.reason,
|
||
run_id=run_id,
|
||
)
|
||
denied_text = denied.message
|
||
tool_history.append(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"result": denied_text,
|
||
"status": "denied",
|
||
"tool_call_id": tool_call_id,
|
||
}
|
||
)
|
||
tool_message = ToolMessage(content=denied_text, tool_call_id=tool_call_id)
|
||
messages.append(tool_message)
|
||
await _publish_message_lifecycle(
|
||
extension_registry, extension_context, tool_message
|
||
)
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.completed",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"status": "denied",
|
||
"result": denied_text[:500],
|
||
},
|
||
)
|
||
continue
|
||
except _ToolSkipped as skipped:
|
||
# registry 未启用：回填"需确认但未启用"，循环继续
|
||
skipped_text = skipped.message
|
||
tool_history.append(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"result": skipped_text,
|
||
"status": "skipped",
|
||
"tool_call_id": tool_call_id,
|
||
}
|
||
)
|
||
tool_message = ToolMessage(content=skipped_text, tool_call_id=tool_call_id)
|
||
messages.append(tool_message)
|
||
await _publish_message_lifecycle(
|
||
extension_registry, extension_context, tool_message
|
||
)
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.completed",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"status": "skipped",
|
||
"result": skipped_text[:500],
|
||
},
|
||
)
|
||
continue
|
||
except Exception as exc: # noqa: BLE001 - 任意工具错误都回填、不中断循环
|
||
# 司命 deny / 沙箱错误 / 未知工具等：错误信息回填，循环继续
|
||
logger.warning(
|
||
"agent_tool_failed",
|
||
tool=name,
|
||
error=str(exc),
|
||
run_id=run_id,
|
||
)
|
||
error_text = f"工具执行失败：{type(exc).__name__}: {_truncate(str(exc))}"
|
||
tool_history.append(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"result": error_text,
|
||
"status": "error",
|
||
"tool_call_id": tool_call_id,
|
||
}
|
||
)
|
||
tool_message = ToolMessage(content=error_text, tool_call_id=tool_call_id)
|
||
messages.append(tool_message)
|
||
await _publish_message_lifecycle(
|
||
extension_registry, extension_context, tool_message
|
||
)
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.completed",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"status": "error",
|
||
"result": error_text[:500],
|
||
},
|
||
)
|
||
continue
|
||
|
||
# 成功路径：扩展可变换结果或提示终止；安全裁定已在 ToolRuntime 内完成。
|
||
if extension_registry.enabled:
|
||
after = await extension_registry.after_tool_call(
|
||
hook_call,
|
||
tool_result,
|
||
extension_context,
|
||
)
|
||
tool_result = after.result or tool_result
|
||
terminate_after_tools = terminate_after_tools or after.terminate
|
||
outcome = _tool_result_text(tool_result)
|
||
status = "success" if tool_result.ok else "error"
|
||
if not tool_result.ok:
|
||
# 沙箱执行返回非 ok（exit_code != 0 等）——不抛异常，回填让模型自决策
|
||
logger.info(
|
||
"agent_tool_returned_error",
|
||
tool=name,
|
||
exit_code=tool_result.exit_code,
|
||
stderr=tool_result.stderr[:500] if tool_result.stderr else "",
|
||
run_id=run_id,
|
||
)
|
||
tool_history.append(
|
||
{
|
||
"name": name,
|
||
"args": tool_input,
|
||
"result": outcome,
|
||
"status": status,
|
||
"tool_call_id": tool_call_id,
|
||
}
|
||
)
|
||
tool_message = ToolMessage(content=outcome, tool_call_id=tool_call_id)
|
||
messages.append(tool_message)
|
||
await _publish_message_lifecycle(extension_registry, extension_context, tool_message)
|
||
if on_tool_event is not None:
|
||
await on_tool_event(
|
||
"tool.completed",
|
||
{
|
||
"tool_name": name,
|
||
"tool_call_id": tool_call_id,
|
||
"status": status,
|
||
"result": outcome[:500],
|
||
},
|
||
)
|
||
|
||
steering = get_steering_messages() if get_steering_messages is not None else []
|
||
if steering:
|
||
messages.extend(steering)
|
||
turn = TurnSnapshot(
|
||
iteration=iterations,
|
||
content=content_buf,
|
||
reasoning=reasoning_buf,
|
||
tool_calls=tuple(tool_calls),
|
||
tool_results=tuple(tool_history[turn_history_start:]),
|
||
usage=usage,
|
||
)
|
||
should_stop = terminate_after_tools
|
||
if extension_registry.enabled:
|
||
await extension_registry.publish(
|
||
AgentEvent("agent.turn.ended", {"iteration": iterations}),
|
||
extension_context,
|
||
)
|
||
should_stop = should_stop or await extension_registry.should_stop(
|
||
turn,
|
||
extension_context,
|
||
)
|
||
if should_stop and not steering:
|
||
return AgentTurnResult(
|
||
content=content_buf,
|
||
reasoning=reasoning_buf,
|
||
tool_history=tool_history,
|
||
iterations=iterations,
|
||
truncated=False,
|
||
usage=usage,
|
||
)
|
||
|
||
# 达上限仍带 tool_calls：截断返回，content 用最后一次模型输出或说明已截断
|
||
content = last_content or f"Agent 循环达到最大次数 {max_iterations}，已截断。"
|
||
return AgentTurnResult(
|
||
content=content,
|
||
reasoning=last_reasoning,
|
||
tool_history=tool_history,
|
||
iterations=iterations,
|
||
truncated=True,
|
||
usage=usage,
|
||
)
|
||
|
||
|
||
__all__ = [
|
||
"DEFAULT_CONFIRMATION_TIMEOUT",
|
||
"DEFAULT_MAX_ITERATIONS",
|
||
"AgentTurnResult",
|
||
"OnChunkCallback",
|
||
"OnToolEventCallback",
|
||
"run_agent_turn",
|
||
]
|