インストール
llama-index-core 0.14.23 〜 0.15。0.14.23 は、このアダプターが読み取る型付きエージェントイベントをワークフローストリームが運ぶようになったリリースです。それより前のバージョンでは、モデル名とエージェント構造の両方が欠落します。
インストルメント
async with と with の両方で動作し、同一のイベントを生成します。
instrument() は LlamaIndex のグローバルディスパッチャーにイベントハンドラーとスパンハンドラーをアタッチします。これにより、モデルの呼び出しだけでなく、エージェントループ全体が可視化されます。
トークン数
FunctionAgent は astream_chat を呼び出しますが、llama-index-llms-openai はストリーミング時に stream_options={"include_usage": True} を送信しません。そのため、プロバイダーは usage チャンクを送信せず、いかなるインストルメンテーションも読み取るデータがありません。
これは上流の LlamaIndex の挙動です。LLM 側でオプトインしてください:
非ストリーミング呼び出し(
llm.chat、llm.achat)は設定なしで usage を報告します。この設定が必要なのは、デフォルトのエージェントパスであるストリーミングパスのみです。
記録される内容
agent_id は FunctionAgent.name を設定した場合はその値、未設定の場合はワークフローのクラス名になります。AgentWorkflow 配下では、ターンを取得した各エージェントがワークフロー下に独立したネストスパンを持つため、ハンドオフは1つのエージェントではなく2つのエージェントとして記録されます。
リトリーバルの出力は、そのまま格納するのではなく要約されます。リトリーバーはドキュメントを返しますが、ペイロードにそのまま格納するとクエリのたびにコーパス全体がイベントストアに入ってしまいます。代わりに件数、スコアの範囲、切り詰めたスニペットが保持されます。
サンプル
init_run、setup_agent、run_agent_step、parse_agent_output、call_tool、aggregate_tool_results。これらはフレームワーク自身のループであるため、エージェントではなくフックとして扱われ、agent_id の意味が保たれます。
スパンに名前を付ける
agent_id は FunctionAgent.name を設定した場合はその値、未設定の場合はワークフローのクラス名になります。
AgentWorkflow 内では、その名前が各ハンドオフの記録名にもなります:
agent_id はどのエージェントが作業を行ったかを示し、parent_id はどのワークフローに属していたかを示します。後でコントロールを引き継いだエージェントは、最初のターンを再開するのではなく、新しいターンを開始します。
実行をラップしてオーバーライドしたり、複数のエージェントを1つの親にまとめることもできます:
agent_id は低カーディナリティに保ってください。これはすべてのダッシュボード画面における主要なファセットです。UUID や実行ごとの文字列ではなく、ロール名やワークフロー名を使用してください。
セッションの制御
このアダプターにはsession_id オプションはありません。セッションは外側のスコープから取得され、指定がない場合はワークフロー実行ごとに生成された uuid4().hex が使用されます:
オプション
ヒューマン・イン・ザ・ループ
待機がツール内で発生した場合にキャプチャされます:ctx.wait_for_event はキャプチャされません。ランタイムがディスパッチャーに到達する前に中断を検知するため、ステップは終了し、一時停止のシグナルがないまま後で再実行されます。LlamaIndex がドキュメントで紹介している FunctionAgent パターンはツール内で待機するため、完全にキャプチャされます。
よくある問題
すべてのトークン数が null になる
すべてのトークン数が null になる
LLM に
additional_kwargs={"stream_options": {"include_usage": True}} を追加してください。トークン数を参照してください。usage は入力されているがトークンの列が空になる
usage は入力されているがトークンの列が空になる
LlamaIndex には標準の usage フィールドがありません。アダプターはいくつかの既知の形式を試みますが、カウンターを異なる名前で定義しているインテグレーションはいずれにも一致しません。生の dict は常に送信されるため、ペイロード内の
usage を確認してプロバイダーがどのような名前を使用しているか確認してください。usage が入力されているにもかかわらずトークンの列が空になるのは意図的な挙動です — 誤った数値を自信を持って表示するよりも適切です。タイムラインが setup_agent と parse_agent_output で埋め尽くされる
タイムラインが setup_agent と parse_agent_output で埋め尽くされる
これは FunctionAgent ループで、イテレーションごとに1セット表示されます。ダッシュボードでフック名によるフィルタリングを行ってください。これらのステップのタイミングは、モデルのみのアダプターではなくこのアダプターを使用する主な理由であることが多いです。
何も記録されない
何も記録されない
以下の順序で確認してください:
instrument() が実行前に呼び出されているか; await の周囲に async with failproofai_sdk.session(): があるか; llama-index-core が 0.14.23 以上か; FAILPROOFAI_SDK_STRICT=1 が設定されていれば、劣化したフックが握り潰される代わりに例外を送出します。次のステップ
仕組みを理解する
ペア、ID、セッションライフサイクル、デリバリーについて。
トレースを読む
キャプチャしたセッションの因果関係を追う。
他のフレームワーク
LangGraph、CrewAI、Pydantic AI、カスタムエージェント。

