📚 参考書籍

※この記事は書籍の一部をベースに再構成しています。もう少し踏み込んだ内容（設計や具体例）は書籍の中でまとめているので、気になる方はそちらもどうぞ。

####『ゼロから触ってわかった！AI Agent Observability入門― MLflow・Databricksで実践するAIエージェントの評価・監視・安全性・説明可能性』
本書は、AI Agentを「作って動かす」だけでなく、その品質をどう観測し、どう評価し、どう守り、どう説明可能にするかを体系的に学ぶための入門書です。
https://link.amazon/B04VaTlR3

⚡MLflow Tracing入門⚡ LLM・Retriever・Toolを1つのTraceで可視化する方法

AI AgentはLLMだけで動きません。RAGの検索や外部システムのToolも利用します。誤回答の原因を特定するには、一連の処理を1つのTraceで記録することが重要です。

1. TraceとSpanの基本

「社員の残り有給休暇を確認するAgent」を例に考えます。

• Retriever：休暇規程を検索
• Tool：人事システムから残日数を取得
• LLM：取得情報から回答を生成

MLflowでは、全体をTrace、各処理をSpanとして記録します。AGENT、RETRIEVER、TOOLなどのSpan Typeで役割を区別できます。

2. Retrieverを記録する

@mlflow.trace(span_type=SpanType.RETRIEVER)で、検索Queryと取得文書を追跡できます。

文書ID・順位・スコアも検索品質の分析に役立ちます。文書出力にはpage_contentとmetadataなどを利用します。

3. LLMはAutologで記録する

OpenAI SDKではmlflow.openai.autolog()を有効にするだけで、対応するLLM呼び出しを記録できます。

• Prompt・Response
• Model名・Token Usage
• Latency・エラー

Responses APIにも対応しています。

4. Toolの引数と結果を記録する

SpanType.TOOLを指定すると、例えば次の情報を確認できます。

• Input：employee_id = E001
• Output：remaining_days = 8

引数と返却結果が障害調査の鍵です。

5. Agent全体を1つのTraceにまとめる

Manual TracingとAutomatic Tracingを組み合わせた例です。検索とToolは説明用の固定値を返します。

[
import mlflow
from mlflow.entities import SpanType
from openai import OpenAI

mlflow.set_experiment("leave-agent")
mlflow.openai.autolog()
client = OpenAI()

@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_policy(query):
return [{
"page_content": "有給休暇は社員ごとの付与日数で管理します。",
"metadata": {"doc_uri": "leave-policy-01"}
}]

@mlflow.trace(span_type=SpanType.TOOL)
def get_remaining_leave(employee_id):
return {"employee_id": employee_id, "remaining_days": 8}

@mlflow.trace(span_type=SpanType.AGENT)
def run_agent(question, employee_id):
docs = retrieve_policy(question)
leave = get_remaining_leave(employee_id)
response = client.responses.create(
model="gpt-4o-mini",
input=f"質問: {question}\n規程: {docs}\n残日数: {leave}"
)
return response.output_text

print(run_agent("残りの有給休暇は何日？", "E001"))
]

Retriever・Tool・LLMが子Spanとして表示されます。この例ではToolを事前に呼び、LLMに選択させていません。

6. Traceで誤回答を切り分ける

Agentが「残り5日」と誤回答した場合、Traceを確認します。

• Retriever：正しい規程を取得したか
• Tool：実際に8日を返したか
• LLM：8日を受け取り、5日と誤生成したか

Toolが正しければ回答生成側、Tool自体が誤っていれば外部APIや元データを調査します。

本番では個人情報のマスキングと閲覧権限も設計します。

まとめると

• Trace：Agent全体の実行履歴
• Span：各処理のInput・Output
• Manual Tracing：独自処理を計測
• Automatic Tracing：LLM呼び出しを自動記録

MLflow TracingはAI Agentをブラックボックスにせず、失敗箇所を調査できる仕組みです。継続監視ではLog・Metric・Eventも組み合わせます。