[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: 幂等性, Tool Error Handling

Tool Idempotency

一句话定义

Tool Idempotency 是确保工具执行多次和执行一次效果相同的特性。网络超时重试时，如果工具不幂等，可能重复扣款、重复发送邮件。

核心原理

天然幂等 vs 需要设计

工具	天然幂等	说明
查询 (SELECT)	✅	查多少次结果一样
写入 (INSERT)	❌	重复写入会创建多条
更新 (UPDATE)	✅	设置为相同值
删除 (DELETE)	✅	删两次和删一次效果一样
发送邮件	❌	重复发送
扣款	❌	重复扣款

幂等实现

class IdempotentToolExecutor:
    def __init__(self):
        self.executed = {}  # idempotency_key -> result

    async def execute(self, tool: Tool, args: dict, context: ExecutionContext) -> ToolResult:
        # 生成幂等 key
        idempotency_key = self.generate_key(tool.name, args, context.user_id)

        # 检查是否已执行
        if idempotency_key in self.executed:
            return self.executed[idempotency_key]

        # 执行
        result = await tool.handler(**args)

        # 缓存结果
        if tool.idempotent:
            self.executed[idempotency_key] = result

        return result

    def generate_key(self, tool_name: str, args: dict, user_id: str) -> str:
        data = f"{tool_name}:{user_id}:{json.dumps(args, sort_keys=True)}"
        return hashlib.md5(data.encode()).hexdigest()

常见坑

1. 不做幂等: 重试导致重复操作
2. 幂等 key 不稳定: 相同操作生成了不同的 key
3. 缓存不清理: 幂等缓存无限增长

参考资料

• Idempotency
• Tool Error Handling