ツール呼び出しと入出力のロギング
各ステップで記録すべき内容を学びます。ツール名、入力引数、出力、レイテンシ、エラー、親span idです。
「ツール呼び出しと入出力のロギング」はCoddyKit上の無料AI Agentsレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはAI Agents学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Agentsコースには全4レッスンが含まれています。
このレッスンの一部はまだ翻訳されておらず、英語で表示されています。
ステップごとに記録する情報
各Spanについて、次の情報を取得します。
- ステップ名（llm_call、tool_call、retrieve）
- 入力（メッセージ、ツール引数、クエリ）
- 出力（レスポンス、ツールの結果）
- メタデータ（モデル、レイテンシー、トークン数、コスト）
- 失敗した場合はエラー情報
自作の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_tokensSpanのネスト
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."))
構造化ログ出力
1つのスパンにつき1つの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))
ユーザーセッションと関連付ける
後からユーザーごとにトレースをフィルタリングできるよう、すべてのスパンにsession_idとuser_idを含めます。
サンプリング
大量のトラフィックを処理するエージェントでは、サンプリングします：
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)")
トレースから再実行する
完全な入力（メッセージ、ツール、引数）を保存しておくと、新しいプロンプトでトレースを再実行し、改善を検証できます。これはeval駆動開発の基盤です。
大きなペイロードを切り詰める理由
ログ内の大きなツール出力を切り詰めるのはなぜでしょうか？
まとめ
すべてのステップ、すべての入力、すべての出力を、構造化し、ネストし、サンプリングします。これが、オブザーバビリティにおけるその他すべての基礎データになります。
よくある質問
「ツール呼び出しと入出力のロギング」レッスンは無料ですか？
はい。「ツール呼び出しと入出力のロギング」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Agentsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Agentsコースには全4レッスンが含まれています。
「ツール呼び出しと入出力のロギング」で何を学びますか？
各ステップで記録すべき内容を学びます。ツール名、入力引数、出力、レイテンシ、エラー、親span idです。 ブラウザで直接実行するハンズオンコードでAI Agentsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
AI Agentsを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのAI Agentsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。
「ツール呼び出しと入出力のロギング」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このAI Agentsレッスンでコードを書いて実行できますか？
はい。すべてのAI Agentsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。