トレース検索API¶
概要¶
Agents SDK Modelsのトレース検索機能は、フロー名やエージェント名でトレースを検索し、実行履歴を追跡・分析するための包括的なAPIを提供します。
主要クラス¶
TraceRegistry¶
トレースの保存・検索を管理するメインクラスです。
メソッド | 説明 | 戻り値 |
---|---|---|
register_trace() |
新しいトレースを登録 | None |
search_by_flow_name() |
フロー名でトレースを検索 | List[TraceMetadata] |
search_by_agent_name() |
エージェント名でトレースを検索 | List[TraceMetadata] |
search_by_tags() |
タグでトレースを検索 | List[TraceMetadata] |
search_by_status() |
ステータスでトレースを検索 | List[TraceMetadata] |
search_by_time_range() |
時間範囲でトレースを検索 | List[TraceMetadata] |
complex_search() |
複数条件による複合検索 | List[TraceMetadata] |
get_statistics() |
トレース統計を取得 | Dict[str, Any] |
export_traces() |
トレースをファイルにエクスポート | None |
import_traces() |
ファイルからトレースをインポート | int |
TraceMetadata¶
トレースのメタデータを表現するデータクラスです。
フィールド | 型 | 説明 |
---|---|---|
trace_id |
str | ユニークなトレース識別子 |
flow_name |
Optional[str] | フロー名 |
flow_id |
Optional[str] | フローインスタンスID |
agent_names |
List[str] | 使用されたエージェント名のリスト |
start_time |
datetime | トレース開始時刻 |
end_time |
Optional[datetime] | トレース終了時刻 |
status |
str | トレースステータス (running, completed, error) |
total_spans |
int | トレース内のスパン数 |
error_count |
int | エラースパン数 |
duration_seconds |
Optional[float] | 総実行時間 |
tags |
Dict[str, Any] | カスタムタグ |
artifacts |
Dict[str, Any] | トレース成果物 |
検索メソッド詳細¶
フロー名による検索¶
# 完全一致検索
exact_matches = registry.search_by_flow_name("customer_support_workflow", exact_match=True)
# 部分一致検索
partial_matches = registry.search_by_flow_name("support", exact_match=False)
パラメータ:
- flow_name
(str): 検索するフロー名
- exact_match
(bool): 完全一致を使用するか(デフォルト: False)
エージェント名による検索¶
# 特定のエージェントを検索
agent_traces = registry.search_by_agent_name("SupportAgent", exact_match=True)
# エージェントパターンを検索
pattern_traces = registry.search_by_agent_name("Agent", exact_match=False)
パラメータ:
- agent_name
(str): 検索するエージェント名
- exact_match
(bool): 完全一致を使用するか(デフォルト: False)
タグによる検索¶
# すべてのタグがマッチする必要がある
all_match = registry.search_by_tags({"env": "prod", "version": "1.0"}, match_all=True)
# いずれかのタグがマッチすればよい
any_match = registry.search_by_tags({"priority": "high"}, match_all=False)
パラメータ:
- tags
(Dict[str, Any]): 検索するタグ
- match_all
(bool): すべてのタグがマッチする必要があるか(デフォルト: True)
時間範囲による検索¶
from datetime import datetime, timedelta
# 過去1時間のトレース
recent = registry.search_by_time_range(
start_time=datetime.now() - timedelta(hours=1)
)
# 特定の期間のトレース
period = registry.search_by_time_range(
start_time=datetime(2024, 1, 1),
end_time=datetime(2024, 1, 31)
)
パラメータ:
- start_time
(Optional[datetime]): 検索開始時刻
- end_time
(Optional[datetime]): 検索終了時刻
複合検索¶
# 複数条件による検索
results = registry.complex_search(
flow_name="support", # フロー名に"support"を含む
agent_name="Agent", # エージェント名に"Agent"を含む
status="completed", # ステータスが"completed"
tags={"priority": "high"}, # タグに"priority": "high"を含む
start_time=datetime.now() - timedelta(days=7), # 過去7日間
max_results=10 # 最大10件
)
パラメータ:
- flow_name
(Optional[str]): フロー名フィルタ
- agent_name
(Optional[str]): エージェント名フィルタ
- tags
(Optional[Dict[str, Any]]): タグフィルタ
- status
(Optional[str]): ステータスフィルタ
- start_time
(Optional[datetime]): 開始時刻フィルタ
- end_time
(Optional[datetime]): 終了時刻フィルタ
- max_results
(Optional[int]): 最大結果数
統計情報¶
stats = registry.get_statistics()
print(f"総トレース数: {stats['total_traces']}")
print(f"ユニークフロー名数: {stats['unique_flow_names']}")
print(f"ユニークエージェント名数: {stats['unique_agent_names']}")
print(f"総スパン数: {stats['total_spans']}")
print(f"総エラー数: {stats['total_errors']}")
print(f"平均実行時間: {stats['average_duration_seconds']:.2f}秒")
戻り値の構造:
{
"total_traces": int,
"status_distribution": Dict[str, int],
"unique_flow_names": int,
"unique_agent_names": int,
"total_spans": int,
"total_errors": int,
"average_duration_seconds": float,
"flow_names": List[str],
"agent_names": List[str]
}
エクスポート・インポート¶
エクスポート¶
インポート¶
# JSONファイルからインポート
imported_count = registry.import_traces("traces_backup.json", format="json")
print(f"{imported_count}件のトレースをインポートしました")
グローバルレジストリ¶
from agents_sdk_models import get_global_registry, set_global_registry
# グローバルレジストリを取得
registry = get_global_registry()
# カスタムレジストリを設定
custom_registry = TraceRegistry(storage_path="custom_traces.json")
set_global_registry(custom_registry)
Flow統合¶
Flowクラスは自動的にトレースレジストリと統合されます:
# フロー作成時に自動的にトレースが登録される
flow = Flow(
name="my_workflow",
steps=my_steps,
start="first_step"
)
# フロー実行後、トレースが更新される
await flow.run("input_data")
# 検索で見つけることができる
traces = registry.search_by_flow_name("my_workflow")
使用例¶
1. 特定エージェントを使用したフローの検索¶
# SupportAgentを使用したすべてのフローを検索
support_traces = registry.search_by_agent_name("SupportAgent")
for trace in support_traces:
print(f"フロー: {trace.flow_name}, 開始時刻: {trace.start_time}")
2. エラーが発生したフローの分析¶
# エラーが発生したトレースを検索
error_traces = registry.search_by_status("error")
for trace in error_traces:
error_step = trace.tags.get("error_step", "不明")
error_type = trace.tags.get("error_type", "不明")
print(f"エラーフロー: {trace.flow_name}, ステップ: {error_step}, エラー: {error_type}")
3. パフォーマンス分析¶
# 完了したトレースの実行時間を分析
completed_traces = registry.search_by_status("completed")
durations = [t.duration_seconds for t in completed_traces if t.duration_seconds]
if durations:
avg_duration = sum(durations) / len(durations)
print(f"平均実行時間: {avg_duration:.2f}秒")
4. 最近のアクティビティ監視¶
# 過去1時間のアクティビティを監視
recent_traces = registry.get_recent_traces(hours=1)
print(f"過去1時間で{len(recent_traces)}件のフローが実行されました")
# ステータス別の分布
status_counts = {}
for trace in recent_traces:
status_counts[trace.status] = status_counts.get(trace.status, 0) + 1
print("ステータス分布:", status_counts)
ベストプラクティス¶
- フロー名の命名規則: 検索しやすいように一貫した命名規則を使用する
- エージェント名の標準化: エージェント名に一貫したパターンを使用する
- タグの活用: 環境、バージョン、優先度などの情報をタグで管理する
- 定期的なクリーンアップ: 古いトレースを定期的に削除する
- エクスポート: 重要なトレースデータは定期的にエクスポートしてバックアップする
注意事項¶
- トレースレジストリはメモリ内に保存されるため、アプリケーション再起動時にはデータが失われます
- 永続化が必要な場合は、
storage_path
を指定してTraceRegistryを作成してください - 大量のトレースを扱う場合は、定期的なクリーンアップを実施してください
- 検索結果は開始時刻の降順(新しい順)でソートされます