Skip to main content

インストール

対応バージョン: llama-index-core 0.14.23 〜 0.15。0.14.23 は、このアダプターが読み取る型付きエージェントイベントをワークフローストリームが運ぶようになったリリースです。それより前のバージョンでは、モデル名とエージェント構造の両方が欠落します。

インストルメント

LlamaIndex のエージェント API は非同期です。すべてのスコープは async withwith の両方で動作し、同一のイベントを生成します。 instrument() は LlamaIndex のグローバルディスパッチャーにイベントハンドラーとスパンハンドラーをアタッチします。これにより、モデルの呼び出しだけでなく、エージェントループ全体が可視化されます。
LLM に追加の引数を指定しないと、トレース内のすべてのトークン数が null になります。下記のトークン数を参照してください。

トークン数

FunctionAgentastream_chat を呼び出しますが、llama-index-llms-openai はストリーミング時に stream_options={"include_usage": True} を送信しません。そのため、プロバイダーは usage チャンクを送信せず、いかなるインストルメンテーションも読み取るデータがありません。 これは上流の LlamaIndex の挙動です。LLM 側でオプトインしてください:
同じ実行・同じモデルでの計測結果: 非ストリーミング呼び出し(llm.chatllm.achat)は設定なしで usage を報告します。この設定が必要なのは、デフォルトのエージェントパスであるストリーミングパスのみです。

記録される内容

agent_idFunctionAgent.name を設定した場合はその値、未設定の場合はワークフローのクラス名になります。AgentWorkflow 配下では、ターンを取得した各エージェントがワークフロー下に独立したネストスパンを持つため、ハンドオフは1つのエージェントではなく2つのエージェントとして記録されます。 リトリーバルの出力は、そのまま格納するのではなく要約されます。リトリーバーはドキュメントを返しますが、ペイロードにそのまま格納するとクエリのたびにコーパス全体がイベントストアに入ってしまいます。代わりに件数、スコアの範囲、切り詰めたスニペットが保持されます。

サンプル

エージェントループはトレース内にフックペアとして表示されます: init_runsetup_agentrun_agent_stepparse_agent_outputcall_toolaggregate_tool_results。これらはフレームワーク自身のループであるため、エージェントではなくフックとして扱われ、agent_id の意味が保たれます。

スパンに名前を付ける

agent_idFunctionAgent.name を設定した場合はその値、未設定の場合はワークフローのクラス名になります。
AgentWorkflow 内では、その名前が各ハンドオフの記録名にもなります:
つまり、agent_idどのエージェントが作業を行ったかを示し、parent_idどのワークフローに属していたかを示します。後でコントロールを引き継いだエージェントは、最初のターンを再開するのではなく、新しいターンを開始します。 実行をラップしてオーバーライドしたり、複数のエージェントを1つの親にまとめることもできます:
agent_id は低カーディナリティに保ってください。これはすべてのダッシュボード画面における主要なファセットです。UUID や実行ごとの文字列ではなく、ロール名やワークフロー名を使用してください。

セッションの制御

このアダプターには session_id オプションはありません。セッションは外側のスコープから取得され、指定がない場合はワークフロー実行ごとに生成された uuid4().hex が使用されます:

オプション

ヒューマン・イン・ザ・ループ

待機がツール内で発生した場合にキャプチャされます:
通常のワークフローステップ内の ctx.wait_for_event はキャプチャされません。ランタイムがディスパッチャーに到達する前に中断を検知するため、ステップは終了し、一時停止のシグナルがないまま後で再実行されます。LlamaIndex がドキュメントで紹介している FunctionAgent パターンはツール内で待機するため、完全にキャプチャされます。

よくある問題

LLM に additional_kwargs={"stream_options": {"include_usage": True}} を追加してください。トークン数を参照してください。
LlamaIndex には標準の usage フィールドがありません。アダプターはいくつかの既知の形式を試みますが、カウンターを異なる名前で定義しているインテグレーションはいずれにも一致しません。生の dict は常に送信されるため、ペイロード内の usage を確認してプロバイダーがどのような名前を使用しているか確認してください。usage が入力されているにもかかわらずトークンの列が空になるのは意図的な挙動です — 誤った数値を自信を持って表示するよりも適切です。
これは FunctionAgent ループで、イテレーションごとに1セット表示されます。ダッシュボードでフック名によるフィルタリングを行ってください。これらのステップのタイミングは、モデルのみのアダプターではなくこのアダプターを使用する主な理由であることが多いです。
以下の順序で確認してください: instrument() が実行前に呼び出されているか; await の周囲に async with failproofai_sdk.session(): があるか; llama-index-core が 0.14.23 以上か; FAILPROOFAI_SDK_STRICT=1 が設定されていれば、劣化したフックが握り潰される代わりに例外を送出します。

次のステップ

仕組みを理解する

ペア、ID、セッションライフサイクル、デリバリーについて。

トレースを読む

キャプチャしたセッションの因果関係を追う。

他のフレームワーク

LangGraph、CrewAI、Pydantic AI、カスタムエージェント。