[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Tool Execution, Timeout Control

Tool Timeout

一句话定义

Tool Timeout 是工具执行的最大允许时间。数据库查询卡住、API 无响应、代码死循环——没有超时控制，一个工具就能阻塞整个 Agent。

核心原理

超时设置

@dataclass
class Tool:
    name: str
    timeout: int = 30  # 默认 30 秒

# 不同工具不同超时
tools = {
    "search_knowledge": Tool(timeout=10),    # 搜索快
    "query_database": Tool(timeout=30),      # 数据库查询
    "execute_code": Tool(timeout=60),        # 代码执行
    "call_external_api": Tool(timeout=45),   # 外部 API
}

Python 实现

async def execute_with_timeout(tool: Tool, args: dict, context: ExecutionContext) -> ToolResult:
    try:
        result = await asyncio.wait_for(
            tool.handler(**args, user_id=context.user_id),
            timeout=tool.timeout,
        )
        return ToolResult(data=result)
    except asyncio.TimeoutError:
        return ToolResult(error=f"Tool {tool.name} timeout after {tool.timeout}s")

超时后的处理

async def handle_timeout(tool, args, context):
    result = await execute_with_timeout(tool, args, context)

    if result.error and "timeout" in result.error.lower():
        # 1. 记录超时
        logger.warning(f"Tool {tool.name} timeout")

        # 2. 尝试降级
        fallback = get_fallback_tool(tool.name)
        if fallback:
            return await execute_with_timeout(fallback, args, context)

        # 3. 告知 LLM
        return ToolResult(error=f"工具执行超时({tool.timeout}秒)，请尝试其他方式")

    return result

常见坑

1. 不做超时: 工具卡死阻塞 Agent
2. 超时太短: 正常执行被误杀
3. 超时后不清理: 底层资源没有释放
4. 所有工具同一超时: 不同工具应该有不同超时

参考资料

• Timeout Control
• Tool Execution