[!info] related notes

• 所属 MOC: Tool Calling Engineering MOC
• 相关: Audit Log, Tool Execution

Tool Audit Log

一句话定义

Tool Audit Log 是记录每次工具调用的详细日志。出了安全事件，需要知道”谁在什么时候调用了什么工具、传了什么参数、得到了什么结果”。

核心原理

日志结构

@dataclass
class ToolAuditEntry:
    timestamp: datetime
    run_id: str
    user_id: str
    tool_name: str
    arguments: dict
    result: any
    error: str = None
    duration_ms: int = 0
    risk_level: str = "low"
    ip_address: str = ""

Python 实现

class ToolAuditLogger:
    def __init__(self, store):
        self.store = store

    async def log(self, entry: ToolAuditEntry):
        # 高风险操作记录完整参数
        if entry.risk_level in ("high", "critical"):
            await self.store.save_full(entry)
        else:
            # 低风险只记录摘要
            await self.store.save_summary(entry)

    async def log_tool_call(self, tool, arguments, result, context):
        entry = ToolAuditEntry(
            timestamp=datetime.now(),
            run_id=context.run_id,
            user_id=context.user_id,
            tool_name=tool.name,
            arguments=arguments,
            result=result.data if not result.error else None,
            error=result.error,
            duration_ms=result.duration_ms,
            risk_level=tool.risk_level,
        )
        await self.log(entry)

常见坑

1. 不记录参数: 只记录了”调用了工具”，不知道传了什么
2. 不记录结果: 不知道工具返回了什么
3. 日志可被篡改: 应该写入独立的只读存储

参考资料

• Audit Log
• Tool Execution