本文へスキップ

LLMトランザクション設定

AI Agent Observabilityでワークフローとエージェントのパターンを計測するための公開API利用ガイドです。

ワークフローおよびAIエージェントの領域を宣言するだけで、そのスコープ内で発生するすべてのLLM API呼び出しが別々のトランザクションではなく、1つのLLMトランザクション配下の「ステップ」としてまとめて収集されます。ユーザーが行うことは領域を示すことだけです。

AI Agent Observabilityのトランザクションの種類​

LLMトランザクションの種類は全3種です。

  • Workflow（既定）— [Workflow] <name>

  • Agent — [Agent] <name>

  • LLMAPI — ワークフローで包んでいない単独の呼び出しは[LLMAPI] Pure LLM APIとして収集されます。

ワークフローの中で別のワークフローが実行されると、親子トランザクションがトラジェクトリ（Trajectory）として連結され、呼び出し関係を追跡できます。

ワークフロートランザクションの設定​

デコレーターとコンテキストマネージャーの2つの形態をどちらもサポートします。

デコレーター​

ワークフロー名が関数単位で固定されている場合に使用します。

from whatap.llm import workflow

@workflow("support_chat")
async def support_chat(conversation_id, message, history):
    intent = await classify_intent(message)   # この中のLLM呼び出しは
    docs   = await retrieve(message)          # すべてこのワークフローの「ステップ」になります
    answer = await generate(message, docs)
    return {"intent": intent, "answer": answer}

コンテキストマネージャー​

ワークフロー名をランタイムに決定する場合や、関数の一部の区間のみを包みたい場合に使用します。

from whatap.llm import workflow

with workflow("ticket_triage"):
    classification = await _classify(ticket_text)
    entities = await _extract(ticket_text)
注意

非同期コードでもasync withではなく、上記のようにwithを使用してください。workflowとagentは同期コンテキストマネージャーであるため、スコープ内でawaitすることは問題ありませんが、async withで開くとエラーが発生します。

エージェントトランザクションの設定​

使用方法はワークフローの設定と同一で、トランザクション名の接頭辞のみが[Agent]に変わります。デコレーターとコンテキストマネージャーの2つの形態をどちらもサポートします。

デコレーター​

エージェントの実行関数が固定されている場合に使用します。

from whatap.llm import agent

@agent("react_agent")
async def run_agent(task):
    ...
    return result

コンテキストマネージャー​

エージェント名をランタイムに決定する場合や、実行区間の一部のみを包みたい場合に使用します。

from whatap.llm import agent

with agent("react_agent"):
    result = await react_agent.run(task)

コードを修正せずに領域を宣言する​

アプリケーションコードを修正できない場合は、設定でワークフローの境界を指定できます。whatap.confに対象メソッドを列挙すると、そのメソッドの実行がそのままワークフローの境界になります。ワークフロー名にはメソッド名が使用されます。

whatap.conf
workflow_method_patterns=myapp:RagService.run, myapp.agent:run_agent

モジュール:クラス.メソッドまたはモジュール:関数の形式で、カンマ区切りで指定します。

自動計測対応フレームワーク​

次のフレームワークは、別途の領域宣言なしでLLMトランザクションが自動的に収集されます。

フレームワーク収集方式
hermes-agentエージェント実行レイヤー（AIAgent.run_conversation）を計測し、[Agent] <name>トランザクションとして登録します。ゲートウェイインバウンド（GatewayRunner._handle_message）は[Workflow] gateway/<platform>トランザクションとして登録され、その中で実行されたエージェントが子トランザクションとして連結されます。
LangGraphコンパイルされたグラフの実行境界（Pregel.invoke / ainvoke / stream / astream）を計測し、グラフ1回の実行 = LLMトランザクション1件として登録します。toolsノードを持つグラフ（create_react_agent）は[Agent]、それ以外は[Workflow]として登録されます。サブグラフは子トランザクションとして入れ子に連結されます。
最終修正：