AI Agents · 课时

记录工具调用和输入/输出

了解每个步骤应记录的内容：工具名称、输入参数、输出、延迟、错误和父级跨度 ID。

记录工具调用和输入/输出 是 CoddyKit 上的免费 AI Agents 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Agents 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Agents 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

每个步骤应记录什么

对于每个 span，请记录：

步骤名称（LLM 调用、工具调用、检索）
输入（消息、工具参数、query）
输出（响应、工具结果）
元数据（模型、延迟、令牌数、成本）
失败时的错误信息

手写 span 辅助函数

不使用框架时，一个最小的辅助函数如下：

from contextlib import contextmanager
import time, uuid

@contextmanager
def span(name, trace_id, parent_id=None):
    span_id = str(uuid.uuid4())
    start = time.time()
    record = {'trace_id': trace_id, 'span_id': span_id, 'parent_id': parent_id, 'name': name, 'start': start}
    try:
        yield record
    except Exception as e:
        record['error'] = str(e)
        raise
    finally:
        record['duration_ms'] = (time.time() - start) * 1000
        save_span(record)

Using It

trace_id = str(uuid.uuid4())
with span('llm_call_planner', trace_id) as s:
    s['model'] = 'gpt-4o-mini'
    s['messages_in'] = messages
    response = client.chat.completions.create(model='gpt-4o-mini', messages=messages)
    s['response'] = response.choices[0].message.content
    s['tokens_in'] = response.usage.prompt_tokens
    s['tokens_out'] = response.usage.completion_tokens

span 嵌套

向下传递 parent_id，使 span 形成一棵树：

with span('agent_step', trace_id) as parent:
    with span('llm_call', trace_id, parent_id=parent['span_id']):
        ...
    with span('tool_call:search', trace_id, parent_id=parent['span_id']):
        ...

工具调用日志

对于工具调用，请特别记录：

工具名称
参数（JSON）
结果（JSON，可能需要截断）
延迟
错误（如果有）

截断大型负载

某些工具结果非常庞大（200KB 的 HTML）。存储前请先截断：

def safe_payload(obj, max_chars=8000):
    s = json.dumps(obj)
    return s if len(s) <= max_chars else s[:max_chars] + '...[truncated]'

PII 脱敏

存储前先删除个人信息：

import re
EMAIL_RE = re.compile(r'[\w\.-]+@[\w\.-]+')

def redact(text):
    return EMAIL_RE.sub('[email]', text)

print(redact("Contact me at alice@example.com for details."))

结构化日志输出

每个 span 输出一条 JSON 记录——将其传输到 ELK、Loki、Datadog 或 BigQuery：

import json
import sys

def save_span(record):
    print(json.dumps(record), file=sys.stderr, flush=True)

demo_record = {'span': 'call_llm', 'duration_ms': 120, 'ok': True}
save_span(demo_record)
print("Logged span:", json.dumps(demo_record))

与用户会话关联

在每个 span 中加入 session_id 和 user_id，以便之后按用户筛选 trace。

采样

对于高流量代理，请进行采样：

import random

def should_trace(user_id):
    return random.random() < 0.10  # 10% of traces
# Always trace errors and slow runs.

random.seed(42)
sampled = sum(should_trace(i) for i in range(1000))
print(f"Traced {sampled} out of 1000 calls (~10% target)")

从 trace 重放

保存完整的输入（消息、工具、参数），这样您就可以使用新提示词重新运行 trace，测试改进效果。这是评估驱动开发的基础。

是否截断大型负载？

为什么要在日志中截断大型工具输出？

回顾

每一步、每个输入、每个输出——结构化、嵌套、经过采样。这些是可观测性中其他一切内容的原始材料。

常见问题解答

「记录工具调用和输入/输出」课时是免费的吗？

是的 — 「记录工具调用和输入/输出」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Agents 课程的其余内容，请升级到 CoddyKit PRO。 AI Agents 课程共包含 4 节课。

「记录工具调用和输入/输出」这节课中我会学到什么？

了解每个步骤应记录的内容：工具名称、输入参数、输出、延迟、错误和父级跨度 ID。你通过在浏览器中直接运行的动手代码来练习 AI Agents，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Agents 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Agents 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「记录工具调用和输入/输出」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Agents 课中编写并运行代码吗？

能。每节 AI Agents 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Agents