AI Agent / 知识点

AI Agent 工具调用速查手册

手册条目

记录决策、工具名称、参数摘要、耗时、结果状态和关联标识,支持追踪与审计。

记录工具调用链路

用于复盘“模型为什么选这个工具、传了什么、执行多久、结果是否可用”。生产环境应把一次 Agent 运行串成同一条 traceId,每次工具调用再分配独立 callId,避免只看到最终答案却无法定位中间失败点。

记录范围

至少记录以下信息:

  • 决策:触发工具调用的简短原因,以及当时采用的选择模式。
  • 调用:工具名称、版本、参数摘要、traceId、callId 和父级标识。
  • 结果:成功或失败状态、耗时、结果摘要、错误类型和重试次数。
  • 环境:Agent 版本、提示词版本、模型标识和请求入口,便于比较不同发布批次。

参数摘要只保留排障需要的字段。结果通常记录字段名、条数、状态码或内容哈希,不直接写入完整响应。

Agent 工具调用链路与关联标识

可运行示例

下面的 Python 示例输出一条结构化调用记录,并对敏感参数做掩码。真实系统可把同一结构发送到日志平台或链路追踪系统。

python
from __future__ import annotations

import json
import time
from datetime import datetime, timezone
from typing import Any

SENSITIVE_KEYS = {"token", "authorization", "password", "secret", "api_key"}

# 日志只保留排障所需摘要,敏感键统一掩码。
def summarize_params(params: dict[str, Any]) -> dict[str, Any]:
    summary: dict[str, Any] = {}
    for key, value in params.items():
        if key.lower() in SENSITIVE_KEYS:
            summary[key] = "***"
        elif isinstance(value, (str, int, float, bool)) or value is None:
            summary[key] = value
        else:
            summary[key] = f"<{type(value).__name__}>"
    return summary

# 真实系统在这里调用外部工具;示例保持确定的返回结构。
def fake_weather(city: str) -> dict[str, Any]:
    time.sleep(0.01)
    return {"temperatureC": 26, "condition": "cloudy"}

def main() -> None:
    trace_id = "tr_demo_001"
    call_id = "call_demo_001"
    tool_name = "get_weather"
    params = {"city": "Shanghai", "api_key": "sk-demo"}

    started = time.perf_counter()
    status = "success"
    error_type = None
    result: dict[str, Any] | None = None

    try:
        result = fake_weather(params["city"])
    except Exception as exc:
        status = "error"
        error_type = type(exc).__name__

    # 成功和异常分支共用同一终态记录,避免只留下“调用开始”。
    duration_ms = round((time.perf_counter() - started) * 1000, 2)
    record = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "event": "tool_call",
        "traceId": trace_id,
        "callId": call_id,
        "parentSpanId": "agent_step_001",
        "decision": "用户询问上海天气,需要读取天气数据",
        "tool": tool_name,
        "argsSummary": summarize_params(params),
        "durationMs": duration_ms,
        "status": status,
        "resultSummary": {"keys": list(result)} if result else None,
        "errorType": error_type,
    }
    print(json.dumps(record, ensure_ascii=False, separators=(",", ":")))

if __name__ == "__main__":
    main()

预期输出

text
{"timestamp":"<TIME>","event":"tool_call","traceId":"tr_demo_001","callId":"call_demo_001","parentSpanId":"agent_step_001","decision":"用户询问上海天气,需要读取天气数据","tool":"get_weather","argsSummary":{"city":"Shanghai","api_key":"***"},"durationMs":<DURATION_MS>,"status":"success","resultSummary":{"keys":["temperatureC","condition"]},"errorType":null}

<TIME> 和 <DURATION_MS> 会随实际运行变化。读取时先按 traceId 聚合一次 Agent 运行,再按时间排序;同一 traceId 下出现多个 callId,表示发生了并行、串行或重试调用。

风险与边界

  • 触发条件:直接记录原始参数、请求头或完整结果。可能后果:密钥、个人信息和业务数据进入日志。安全替代:字段白名单、掩码、哈希和访问分级同时启用。
  • 触发条件:大响应、流式分片或二进制内容全部落盘。可能后果:日志成本激增并拖慢主链路。安全替代:只存条数、大小、哈希、对象存储引用和截断摘要。
  • 触发条件:不同服务使用不同时间格式或重复生成关联标识。可能后果:链路无法排序或错误合并。安全替代:统一 UTC、集中生成 traceId,并给日志结构增加版本号。

排障清单

调用链缺口通常按以下顺序检查:请求入口是否生成 traceId,工具执行器是否透传它,异常分支是否仍写结束事件,超时和取消是否标记独立状态,重试是否复用原 traceId 并创建新 callId。只记录“开始”不记录“结束”,会造成调用永久处于运行中,应在 finally 或等价清理逻辑中补写终态。

目录与阅读设置

记录一个想法

AI Agent 工具调用速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通