# Floviaとは エージェントがプロダクトをどう発見し、選択し、利用するかを理解する。失敗した箇所を、次の改善につなげます。 出典: https://flovia.dev/docs/ja/ ## エージェント体験を改善する評価サイクル Floviaは、APIやMCPツールを開発するチームのためのAgent Experience Optimizerです。AIエージェントがプロダクトを選び、正しく使い、ユーザーのタスクを完了できるかを評価します。どの段階でつまずいたかを特定し、具体的な修正と再検証につなげます。 プロダクトが候補に挙がっても、呼び出すエンドポイントや引数を誤ればタスクは完了しません。Floviaは、言及されたかどうかの先まで追跡し、API、ツールの説明、ドキュメントのどこを変えれば正しく使われるようになるかを特定します。 AX Simulationは、Floviaの評価手法です。エージェントの動作を、条件を統制した実験として評価します。タスクに基づくシナリオ、ネイティブな関数呼び出し、入出力仕様の検証、段階別の採点を組み合わせ、プロダクトの選択からタスク完了までの障害を特定します。その後、条件を揃えたペア実験で、対象を絞った変更の前後を比較します。専用ダッシュボードでは、証拠から修正案、再検証までを確認できます。 利用する際は、評価を依頼し、Floviaのチームと対象範囲を決めます。結果、失敗の分析、修正案、再検証の結果は、専用ダッシュボードで確認できます。 - **定義:** タスクと成功基準 - **シミュレーション:** モデルとツール環境 - **診断:** 評価段階と証拠 - **改善:** 変更と条件を揃えた再検証 ## 例：APIの使い方の案内を改善する ブロックチェーンのデータを提供するAPIで、ドキュメント更新前後のAIの回答を比較しました。更新前は取得方法を特定できなかったり、別の用途の機能を案内したりしていましたが、更新後は取引IDだけを取得する正しい方法を案内できるようになりました。 リアルタイム配信でも、更新後は「接続情報を取得するだけでは配信は始まらず、開発者が接続処理を実行する必要がある」と正しく説明できました。 - [改善事例を詳しく見る](https://flovia.dev/docs/ja/improvement-loop/): 機能ごとの変更前後の比較を紹介します。 ## 評価結果をダッシュボードで確認する 評価の概要から、優先する改善、根拠となる実行記録、実装用プロンプトまで確認できます。指摘の理由を確かめてから修正に進めます。 - [ダッシュボードの画面例を見る](https://flovia.dev/docs/ja/improvement-loop/#dashboard-example): 概要、指摘、証拠を同じ例でたどります。 ## プロダクトの判断につながる技術 エンジンは、実験設計、実行可能なタスクの検証仕様、証拠をたどれる測定を組み合わせます。各評価では、確認したい問いと実行経路に適した手法を選びます。 | 手法 | 観測できること | プロダクトの判断 | | --- | --- | --- | | ペア比較＋ラテン方格による候補位置の均衡化 | 説明文の変更前後の動作（対応する実験では、タスクと候補位置を統制） | どの説明を、さらに多くのユースケースで再検証するか？ | | スキーマ＋引数の意味検証 | 選択した操作と引数が、タスクの検証仕様を満たすか | ツール名、パラメーターの説明、操作の役割分担のどこを変えるか？ | | 結果の検証＋基準に基づく回答評価 | 返されたデータや最終回答のどこが、タスクの要件を満たさないか | どのフィールドや解釈の説明があれば完了に進めるか？ | | クラスターブートストラップ＋バージョン管理された証拠 | タスク群を考慮した不確実性（対応する指標の場合）と、各結果の元になった入力 | 結果を支える証拠はどの程度あり、次に何を検証すべきか？ | ## 評価依頼から改善まで 最初の評価は無料です。30分の打ち合わせで、APIやMCPを使ってエージェントに完了してほしいタスクを決めます。Floviaが評価を実行し、専用ダッシュボードで最初の結果をお届けします。 1. 情報を用意する。プロダクトとドキュメントのURL、代表的なタスク、すでに分かっているつまずきを共有します。 2. 30分の打ち合わせで評価範囲を決める。お客様のチームとFloviaで、対象タスク、モデル、実行環境、成功基準を確認します。 3. 評価結果を確認する。Floviaが評価を実行し、つまずいた箇所、根拠となる実行記録、修正案を専用ダッシュボードにまとめます。 4. 修正を実装する。お客様のチームが修正案をレビューし、自社環境に反映します。Enterpriseでは、レビューとデプロイの判断をお客様側に残したまま、GitHub連携による半自動修正も選べます。 5. 改善を確かめる。Floviaが同等の条件で再検証し、変更前後の結果を一緒に確認して、次の改善を決めます。再検証はご利用プランの範囲に応じて実施します。 ## 用意するもの | 入力 | 目的 | | --- | --- | | プロダクトのドキュメントとインターフェースの説明 | エージェントが学べる情報と、利用できる操作を定義します。 | | 代表的なユーザーリクエスト | プロダクトにとって重要なタスクを評価の軸にします。 | | 期待する動作と必要な事実 | タスクが正しく完了したかを検証可能にします。 | | 関連する代替候補と制約 | 別のツールの方が適切なケースも含め、選択の妥当性を評価できるようにします。 | | 変更案がある場合はその内容 | 条件を統制した比較に使うベースラインと変更版を定義します。 | まず公式サイトから評価をご依頼ください。Floviaが評価エンジンを運用し、結果、失敗分析、修正ガイダンス、再検証結果を専用ダッシュボードで提供します。チームは修正内容をレビューし、自社環境に反映します。 評価を始める前に、使用するモデルのエンドポイントとJudge、ツール応答データの準備担当、対象タスクと反復回数、結果を確認する時期をFloviaと決めます。評価計画に記録しておくと、準備の分担と、結果で判断したいことが明確になります。 ## 評価依頼を準備する 依頼用テンプレート · コピーして記入 ```text プロダクト・ドキュメントのURL： エージェントに完了してほしいタスク： 期待する結果・必要な情報： 比較したい候補： 既知の失敗・試したい変更： 制約・Floviaに確認したいこと： ``` - [エージェントと依頼をまとめる](https://flovia.dev/skills/prepare-flovia-evaluation/SKILL.md): ドキュメントを読み、評価依頼をまとめるためのスキルです。シミュレーションの実行機能は含みません。 - [プランと料金（英語）](https://flovia.dev/pricing): 現在のプランと、各プランに含まれる内容を確認できます。 - [評価について相談する（英語）](https://flovia.dev/contact): プロダクトとタスクをチームに共有します。非公開資料を渡す前に、対象範囲やデータの取り扱いを確認してください。 ## 評価手法を詳しく読む - [シナリオを設計する](https://flovia.dev/docs/ja/scenario-design/): 判断したいことを、成功基準を検証できるタスクに落とし込みます。 - [シミュレーションエンジンの仕組み](https://flovia.dev/docs/ja/simulation-engine/): モデル呼び出し、ツールの入出力仕様、採点の流れを確認します。 - [7段階のエージェントファネル](https://flovia.dev/docs/ja/agent-funnel/): 各段階の測定対象と、失敗箇所の特定方法を確認します。 - [条件を統制した比較実験](https://flovia.dev/docs/ja/controlled-experiments/): ペアリング、候補順序のローテーション、比較設計を理解します。 - [指標と証拠](https://flovia.dev/docs/ja/metrics-and-evidence/): 分母、不確実性、結果を裏付ける証拠の読み方を確認します。 --- # シミュレーションエンジン モデルの判断、ツール呼び出し、タスク完了を、条件を統制した環境で観測します。 出典: https://flovia.dev/docs/ja/simulation-engine/ ## タスクから、追跡可能なエージェントの実行過程へ エージェントがつまずく原因が、プロダクトの選択、操作の呼び出し、返されたデータの利用のどこにあるのかを切り分けます。エンジンが各段階の動作を記録するため、どの説明やインターフェースを直すべきかを具体的に検討できます。 Floviaのシミュレーションエンジンは、評価計画を個別に識別できる実行単位へ展開します。各実行には、タスク、モデル、候補の提示条件、実行経路、反復、入力のバージョンが結び付きます。段階別評価ではPromptCaseを使います。これは、許可する操作、引数の期待値、結果に必要なフィールド、完了基準まで含むタスク定義です。 エンジンは、判断と検証を分けることで、エージェントの実行過程を観測できるようにします。モデル呼び出しからは候補の選択、ツール呼び出し、回答が得られます。決定的なチェックでは、ツールの識別、引数、結果の構造を検証します。別途設定するモデル補助のJudgeが、タスクの評価基準に照らして最終回答を判定します。 - **モデル:** 発見と選択 - **入出力仕様:** 操作の特定と検証 - **実行環境:** 実行と結果の確認 - **評価:** 回答と採点 ## モデル呼び出しの流れ | 評価段階 | 入力 | 観測する出力 | | --- | --- | --- | | 発見と選択 | ユーザーのタスクと、定義した候補の提示条件 | 構造化された候補一覧、順位、選択したプロバイダー | | ツール呼び出し | タスク、ツールの説明、入力スキーマ | 関数呼び出し名と構造化された引数 | | 回答生成 | タスクと正規化済みのツール結果 | 返されたデータに基づく最終回答 | | 完了評価（設定した場合） | 回答、ツール結果、固定した完了基準 | 基準ごとの判定、欠けている事実、裏付けのない主張 | モデルの判断を段階ごとに確認し、次へ進む条件を満たしているかを検証します。条件を満たさない場合はそこで実行を止め、失敗した箇所とその根拠を記録します。 ## モデル呼び出しとツール実行は別の経路 PromptCaseのLive LLM / Mock Tool経路では、指定したモデルのエンドポイントを実際に呼び出し、対象ツールの実行には、fixtureと呼ぶバージョン管理された準備済み応答を使います。応答環境を一定に保つことで、エージェントの判断、呼び出し、返されたデータに基づく回答がどう変化するかに焦点を当てられます。 operation bindingは、選択したツールと引数をリクエスト仕様に対応付けます。fixture adapterはリクエストの表現をローカルで組み立て、ツールと引数の条件に合う応答を返します。そのリクエストを対象プロバイダーへ送信することはありません。この仕組みにより、安定したツール環境で、呼び出しの誤りや結果に基づかない回答を調べられます。 | 実行経路 | 確認できること | | --- | --- | | 実際のモデル呼び出し | 測定期間中に、要求したモデルのエンドポイントで観測した動作 | | fixtureに基づくツール実行 | 定義した応答仕様と準備済みの結果に対する動作 | | 準備済みのモデル応答を使うオフラインテスト | パイプラインと成果物の検証。実際のモデル動作の観測ではありません。 | > **実行結果の読み方.** fixtureに基づく実行の成功は、シミュレーション経路上での成功を示します。プロバイダーの実APIの可用性、認証、レイテンシ、本番環境の信頼性を測定したものではありません。 ## 入力のバージョン管理による再現性 PromptCase、ツールカタログ、operation binding、fixture、採点プロンプトは、バージョンまたはハッシュで管理します。実行前にはそれぞれの整合性を検証します。期待するツールがカタログに存在するか、引数の意味的な期待値を解決できるか、必要な結果の事実に検証仕様があるかを確認します。 各実行には識別情報、段階別の記録、エラー、採点の来歴を保持します。並列数の制限、チェックポイント、再開機能により、個々の観測を保持しながら、定義した実行集合を処理します。ここでいう再現性は、条件を追跡でき、同じ手順を繰り返せることです。後日同じモデルのエンドポイントを呼び出しても、回答が異なる可能性はあります。 ## 評価範囲と比較条件を設計する Floviaは、利用目的、ペルソナ、モデル、候補の提示条件を実験要因として扱います。調べたい動作に合わせて評価ケースを構成し、比較する条件と固定する条件を明確にします。 - シナリオ行列：目的とペルソナを組み合わせて診断し、モデル別・目的別の結果を比較します。どの条件で選択されにくくなるかを調べ、次に検証する説明や使用例を選びます。 - 候補位置の均衡化：対応する比較実験では、循環ラテン方格で候補の順序を入れ替えます。各候補が各位置に現れるようにし、同じ順序の中で変更前後を比較します。 - ツール応答の固定：バージョン管理したfixtureを使い、同じタスクに対して返すデータを揃えます。応答データの変動を抑え、説明文やツール情報の変更が判断・呼び出し・回答にどう影響するかを調べます。 --- # シナリオ設計 プロダクトのユースケースを、文脈・ツール仕様・測定可能な成功基準を持つタスクに落とし込みます。 出典: https://flovia.dev/docs/ja/scenario-design/ ## シナリオは、プロンプトだけでは決まらない まず、お客様のユーザーがエージェントに任せたいタスクを選びます。成功の条件を先に決めておくことで、プロダクトを正しく使えたか、どの使用例や説明を補うべきかを判断できます。 有用なシミュレーションケースには、ユーザーの依頼と、評価器が成功をどう判定するかの両方が必要です。FloviaのPromptCaseは、自然言語のタスクと、対象プロバイダー、許可するツール計画、引数の意味的な期待値、必要な事実、回答基準を結び付けます。 意図、言語、難易度、ペルソナ、プロンプトファミリーといった属性により、どのタスクが、どのような利用者の条件で失敗したかを分析できます。ペルソナはシナリオ上の文脈であり、実測した人間のユーザー集団を再現するものではありません。 | 層 | 定義する内容 | | --- | --- | | ユーザーのタスク | 具体的な情報要求、制約、ユーザーが指定する識別子 | | 候補の提示条件 | 候補を与えるかどうか、候補のメタデータと順序 | | ツール仕様 | 許可する操作、入力スキーマ、引数の意味的な期待値 | | 結果の仕様 | 必要なフィールド、型、該当する場合は期待値 | | 完了の評価基準 | 最終回答が満たすべき事実と制約 | ## ペルソナと目的をシナリオ行列で比較する 現行の診断分析には、ペルソナ×目的の全要因計画が含まれます。定義した3つのペルソナと5つの目的を掛け合わせた15セルを対象に、モデル別の結果を保持したまま、同じ目的の中でペルソナを比較し、その差を集計します。これは特定の診断経路の設計で、PromptCaseのファネル実行はそれぞれに定義した設計を使います。 この構造により、選択の傾向が一つのユースケースに集中するか、複数の文脈に共通するかを調べられます。探索的な比較から、次に再検証するオンボーディングの使用例やドキュメントの変更案を選べます。 ## 例：指定日の為替レートを取得する 架空の為替レートAPIを例にします。ユーザーは、特定の日付のEUR→USDレートを知りたいとします。このケースでは、エージェントが過去データの操作を選び、基準通貨と相手通貨を正しく指定し、結果と整合する回答を返すかを検証します。 評価要件の例 · 実行用の設定ではありません ```text タスク：2026-01-15のEURからUSDへの為替レートを取得する 許可する操作：get_historical_rate 引数：base=EUR, quote=USD, date=2026-01-15 必須の結果：base, quote, date, rate 完了基準：返されたレート、通貨の方向、日付を回答する 環境：実際のモデル呼び出し＋準備済みのツール応答 ``` ユーザーの依頼には、引数を導くのに必要な情報を含めます。評価器側の期待回答は、エージェントに与えるタスクとは分けて管理します。最新レートの操作を呼び出したモデルは、最終回答の文章がもっともらしくても、Tool Resolutionで失敗になり得ます。 ## 改善につながる失敗を見つける設計 - プロダクトが対応できる、具体的な対象適合タスクを含めます。 - 競合の方が適切なタスクや負の対照を含め、常に自社プロダクトを選ぶ動作を良い結果と取り違えないようにします。 - 操作、対象エンティティ、日付範囲、言語、曖昧さ、ユーザーの文脈など、意味のある次元でタスクを変化させます。 - プロンプトファミリーと反復を使い、表現の違いへの感度と、同じ依頼に対する一貫性を分けて見ます。 - 選択だけを評価する対照ケースと、実行ファネル全体の評価対象になるタスクを分けます。 反復を増やすと、既存タスクでの動作のばらつきをより詳しく見られます。シナリオの範囲を広げると、別の問い、つまり結果がより多くのユースケースで成り立つかに答えられます。レポートでは、この二つを区別して示します。 ## 実行前に比較条件を固定する 評価計画には、タスク集合、モデル設定、候補の提示条件、実行経路、反復、採点規則、測定期間を記録します。変更の効果を調べる場合は、変更を許可するフィールドも明示します。これにより、試してみたい案を、条件が定義された実験に変えます。 - [比較実験を設計する](https://flovia.dev/docs/ja/controlled-experiments/): 周辺条件を固定し、ベースラインと変更版をペアにします。 --- # エージェントファネル プロダクトの発見からタスク完了までを7段階に分け、各遷移で具体的な条件を検証します。 出典: https://flovia.dev/docs/ja/agent-funnel/ ## タスク完了までの経路全体を測定する ファネルは、どこを改善するかを決めるために使います。プロダクトを選ばない場合と、選んでも引数を間違える場合とでは、必要な修正が異なります。最初に失敗した段階の記録を確認し、試す変更を絞り込みます。 7段階のファネルは、候補に挙がることと、正しく利用されることを分けて捉えます。対象プロダクトが適合するタスクでは、各段階は前の段階の通過を前提とします。段階別の結果から、どこまで動作し、次のどの条件で進めなくなったかを特定します。 | 段階 | 確認する問い | 証拠・チェック | | --- | --- | --- | | Discovery（発見） | 明示的な候補集合に対象が現れるか？ | 候補の識別、存在、回答中の順位 | | Selection（選択） | エージェントは対象を選ぶか？ | 選択したプロバイダー、競合の選択、選択の見送り | | Tool Resolution（操作の特定） | 許可された操作を選ぶか？ | ケースで許可した計画とツールの識別情報との一致 | | Invocation（呼び出し） | 引数の構造と意味は正しいか？ | 入力スキーマと、タスク固有の引数の期待値 | | Execution（実行） | 設定した実行経路で操作が成功するか？ | 設定したツール環境での実行記録 | | Result Usability（結果の利用可能性） | タスクに必要なデータが結果に含まれるか？ | 必須フィールドの存在、型、非null、定義した期待値 | | Completion（完了） | 最終回答がタスクの要件を満たすか？ | 固定した基準と返された事実に照らした回答評価 | ## 最初に失敗した段階を読む プロダクトが選ばれても、別のエンドポイントが呼ばれた場合は、ツール名、説明、操作カタログを確認します。正しいエンドポイントに誤った引数が渡された場合は、パラメーターの意味と使用例を確認します。結果が利用可能でも最終回答が不十分な場合は、完了評価が指摘した欠落や裏付けのない主張を確認します。 前の段階で停止した場合、実行記録上では後続の段階は未観測になります。累積ファネル指標では、その実行を後続の段階に到達しなかったものとして数えることがあります。一方、条件付き遷移率は、それぞれの適格な母集団を使います。これは同じ実行を異なる観点で集計したもので、呼ばれていないツールが失敗した証拠ではありません。 ## 決定的なチェックとJudge Tool Resolution、Invocation、Result Usabilityは、明示した仕様に照らして検証します。完了判定のJudgeには、最終回答、タスク、返されたデータ、基準一覧を渡します。Judgeは、情報の欠落、矛盾、ツール結果では裏付けられない主張を評価します。 Judgeの出力は、採点の来歴を記録したモデル補助評価です。必要なJudgeの結果が欠けている、または取得できない場合、完了評価は欠測として記録し、合格として扱うことはありません。一部の負の対照ケースでは、決定的な終端判断を使い、そのケースの適格性に従って報告します。 Judgeは、完了状態、条件ごとの判定、不足した要件、裏付けのない記述を返します。エンジンは応答の形式を検証し、完了状態と判定の詳細が矛盾していないかを確認します。採点記録には、採点基準とJudgeの識別情報に加え、回答と参照入力のハッシュを保持します。 ## 例：最終回答をどう確認するか 過去の為替レートを調べるタスクでは、正しくツールを呼び出した後、返されたレート、通貨の方向、指定日を回答で伝える必要があります。これらを個別の完了条件として定義します。 回答確認の説明例 · 架空の為替API ```text タスク：2026-01-15のEURからUSDへの為替レートを調べる。 ツール結果：base=EUR, quote=USD, date=2026-01-15, rate=1.10 回答：1 EURは1.10 USDです。 ``` | 条件 | 回答中の根拠 | 想定する判定 | | --- | --- | --- | | 返されたレート | 1.10がツール結果と一致 | 条件を満たす | | 通貨の方向 | EURからUSDへの換算だと分かる | 条件を満たす | | 指定日 | 日付の記載がない | 必要な情報が不足 | 次に直す対象は、回答に日付が含まれない点です。日付フィールドの意味と、回答での使い方の説明を確認します。条件ごとの判定があることで、前段のツール検証を通過した後の問題も切り分けられます。 - [タスクと完了条件を定義する](https://flovia.dev/docs/ja/scenario-design/): 過去の為替レートの例で、必要な情報を確認します。 - [次の修正を選ぶ](https://flovia.dev/docs/ja/improvement-loop/): 最初に失敗した段階を、具体的な修正と再検証につなげます。 ## ファネルにおけるDiscoveryの意味 Discoveryは、モデルが明示的に返した候補一覧に対象が含まれるかを記録します。候補を固定した実験では候補はあらかじめ与えられているため、そこでの出現は、提示条件を統制した下での動作確認であり、エージェントがウェブ上で自力でプロダクトを見つけたことを示すものではありません。 - [指標を正しく読む](https://flovia.dev/docs/ja/metrics-and-evidence/): 累積率、条件付き遷移率、欠測の違いを理解します。 --- # 比較実験 プロダクトの情報面への変更を切り分け、事前に定めた実験設計の下でエージェントの動作を比較します。 出典: https://flovia.dev/docs/ja/controlled-experiments/ ## 実験の前に、答えたい問いを選ぶ ドキュメントやツールの説明を変えることで、エージェントがプロダクトを選びやすく、正しく使いやすくなるかを比較します。まず確認したいことを決め、その問いに関わる部分だけを変更します。 | 実験設計 | 答えられる問い | | --- | --- | | 候補を提示しない評価（別の実験設計） | モデルは自力でどのプロバイダーを挙げるか？ 現行のPromptCaseの発見用プロンプトは、候補一覧を与えずにプロバイダーを挙げさせることができます。測定するのはモデルが挙げた候補であり、ウェブからの取得を示すものではありません。検索を伴う評価には、別途設定した取得経路とその実行証拠が必要です。 | | 固定候補での比較 | 指定した代替候補の中から、エージェントはどのプロバイダーを選ぶか？ | | ペア化したメタデータA/B | 同じ候補環境の中で、指定した説明文の変更が動作にどう影響するか？ | これらの設計は、それぞれ異なる問いに答えます。説明文の実験は、与える情報を統制して判断への影響を調べます。発見の評価は、定義した取得条件の下で対象が現れるかを調べます。固定候補内での改善量は、自然発見の結果ではありません。 ## 評価の目的に合う分析方法を選ぶ Floviaでは、タスクの失敗を診断する場合、説明文の変更をファネル全体で比較する場合、プロバイダー選択の改善量を推定する場合で、分析方法が異なります。結果から何を判断したいかに合わせて選びます。 | 評価 | 比較・確認するもの | 結果のまとめ方 | | --- | --- | --- | | PromptCaseファネル | タスクごとのエージェントの判断と、定義した条件の検証結果 | 段階別の率と条件付き遷移率。対応する率指標では、プロンプト単位のクラスターブートストラップで区間を推定 | | PromptCaseメタデータA/B | 対応付けた変更前後の実行をファネル全体で比較。候補のローテーションは実験設計に従う | 段階別の差、欠測、改善・悪化したペア。候補順序ごとの結果は等しい重みで統合 | | 選択率の改善量を測る実験 | 変更前後のメタデータによるプロバイダー選択 | 条件を満たす完全なペアを使用。実験で定めた目的または言い換えグループ単位の重み付けと、ペアのクラスターブートストラップによる区間推定 | ファネルA/Bの集計と、選択率の改善量の推定は別の分析です。確認実験では、記録されたサンプルサイズの決定根拠と証拠の確認も必要です。評価範囲を決める際に、分析方法、候補のローテーション、区間推定の方法、確認実験の要件を合意します。 ## ベースラインと変更版をペアにする メタデータA/Bでは、ベースラインと変更版で、タスク、要求するモデル、反復、候補順序、介入対象外の入力を共有します。変更するのは、計画で指定した対象フィールドだけです。実験によって、Discoveryの説明、Invocationの説明、またはその両方を変更対象にします。 比較単位の概念例 ```text 共通条件：タスク × モデル × 反復 × 候補順序 × 実行経路 ベースライン：元の対象説明文 変更版：修正した対象説明文 固定するもの：競合メタデータ、ツールスキーマ、fixture、採点規則 比較するもの：選択、呼び出し、完了、失敗した段階 ``` DiscoveryとInvocationの説明を同時に変更した場合、その結果は両方を合わせた介入の効果を測定します。差をどちらか一方の説明に帰属させるには、その説明だけを変える設計が必要です。 ## 候補の表示位置による影響を統制する 候補の順序は実験要因の一つです。対応するメタデータ実験では、循環ラテン方格によるローテーションを使い、各プロバイダーが各候補位置に現れるようにします。同じ順序の中でベースラインと変更版をペアにし、集計では各ラテン順序に等しい重みを与えて統合できます。 ペアリングは周辺のシナリオ条件を固定し、ローテーションは対象が現れる位置を均衡化します。この二つを組み合わせることで、代替候補の見せ方にエージェントが影響を受ける場合でも、説明変更の比較を解釈しやすくします。 | ローテーション | 位置1 | 位置2 | 位置3 | | --- | --- | --- | --- | | A | 対象 | 代替候補1 | 代替候補2 | | B | 代替候補1 | 代替候補2 | 対象 | | C | 代替候補2 | 対象 | 代替候補1 | この例は候補位置の均衡化を説明するもので、顧客の実験結果ではありません。実行順序や、ベースラインと変更版のどちらを先に実行するかの均衡化は、選択した実験計画に従い、すべての評価で行うわけではありません。 ## 比較結果を、検証した範囲で解釈する ペア差は、指定したタスク、モデル、候補環境、測定期間において、ベースラインと変更版で動作がどう変わったかを推定します。ペアの充足状況、欠測、モデル別の結果、実際に使った推定方法と併せて読みます。 記述的なファネルA/Bの結果だけでは、統計的有意性や一般的な因果効果は示せません。確認実験には、事前に定めた証拠要件と適格性要件があります。本番環境での影響を主張するには、統制したシミュレーション比較を超える証拠が必要です。 - [比較結果を改善につなげる](https://flovia.dev/docs/ja/improvement-loop/): 段階別の証拠から修正案を選び、次の再検証を定義します。 --- # 指標と証拠 結果を、母集団・不確実性・実行条件・裏付けとなる実行記録と併せて読みます。 出典: https://flovia.dev/docs/ja/metrics-and-evidence/ ## まず分母を確認する 評価結果は、どの変更を採用し、次に何を検証するかを決めるために使います。対象のタスクとモデルを確認し、変更前後の結果を比べ、実行記録から何が変わったのかを読み取ります。 率を読むときは、まず何を数えたかを確認します。Floviaの指標には、推定値、該当する場合は分子と分母、評価対象の実行数、欠測数、利用できる場合は区間推定の方法を記録します。段階への累積到達率と条件付き遷移率では、母集団が異なります。 | 見方 | 読み方 | | --- | --- | | 段階への累積到達率 | 定義した母集団のうち、何件がこの段階に到達したか？ 前の段階での脱落は、後の段階への到達率にも影響します。 | | 条件付き遷移率 | 前の段階で条件を満たした実行のうち、何件が次の段階を通過したか？ | | タスク全体の完了率 | 評価対象のタスクのうち、何件が評価経路全体を通じて完了したか？ | | ペア比較による改善量 | 対応付けたベースラインと変更版の観測で、結果はどう異なったか？ | 計算の説明例 · 顧客の実測値ではありません ```text # 説明用の数値です。顧客の実測値ではありません。 評価対象100タスク → 選択60件 → 有効な呼び出し45件 選択への到達率：60 / 100 = 60% 呼び出しへの到達率：45 / 100 = 45% 選択から呼び出しへの遷移率：45 / 60 = 75% ベースラインの完了率：30% 変更版の完了率：42% 差：+12パーセントポイント ``` インフラエラー、未観測の段階、Judge結果の欠測は、それぞれ意味が異なります。除外と欠測の扱いは、選択した指標の定義に従います。完全な適格ペアを使う推定方法もあれば、計画した母集団の集計として欠測を分母に残すものもあります。一般的な計算式より、レポートに明示された方針を優先して読みます。 ## 同じタスクの反復を考慮する 同じプロンプトを繰り返した実行は、互いに関連する観測です。選択した指標が対応している場合、エンジンはプロンプト単位または意図単位のクラスターブートストラップで区間を推定します。タスクのクラスターをまとめて再標本化することで、そのまとまりを保ちます。対応する評価経路のメタデータ改善量の推定には、ペア化したクラスターブートストラップを使えます。 区間を報告するのは、選択した方法の要件を満たす場合だけです。区間がないことは、不確実性がゼロという意味ではありません。モデル間で動作が異なる場合やタスク集合が小さい場合は特に、全体集計とともにモデル別・タスクファミリー別の結果を確認します。 確認実験に対応する評価経路では、カバレッジ、サンプル数、推定の精度、元の実行までたどれる証拠が、あらかじめ決めた要件を満たすかを確認します。これにより、有望な初期結果と、確認実験の基準を満たした結果を区別できます。記述的なファネルA/Bには、その評価で定義した推定方法を適用します。 ## 結果から個々の実行までたどる - **計画:** 評価範囲と入力バージョン - **実行:** 判断と結果 - **採点:** チェックと評価基準 - **知見:** 指標と診断 - 評価の定義：タスク、プロンプト、モデル、候補条件、実行経路、測定期間。 - カバレッジ：計画した実行と完了した実行、欠測、除外、失敗理由。 - 実行の証拠：候補と選択の出力、ツール呼び出し、引数検証、実行結果、到達した場合の回答。 - 採点の来歴：決定的なチェック、Judgeの状態、評価基準、選択した採点バージョン。 - 比較の証拠：ベースラインと変更版の識別情報、変更フィールド、ペアリング、推定方法、該当する適格性確認。 ## 適用範囲：結果が答えられること 評価は、検証したタスク、モデル、候補の提示条件、実行環境、測定期間に結び付きます。この範囲を確認すると、変更を採用できるか、追加で何を検証すべきかを判断できます。 | 証拠 | 判断に使えること | 追加の証拠が必要なこと | | --- | --- | --- | | 固定候補での比較 | 提示した候補の中での選択や利用の変化 | 候補を提示しない場合の発見や、ウェブからの取得 | | fixture環境での実行 | 定義した応答仕様に対する呼び出しと回答の正しさ | 実APIの可用性、認証、レイテンシ | | 条件を揃えた再検証 | 検証範囲で改善した段階と、残る失敗の特定 | 顧客の本番利用、コンバージョン、売上への影響 | 要求したモデルの識別情報は記録します。実際に応答したモデルを特定するには、プロバイダー側の証拠も必要です。反復や関連タスクでの追加検証によって、初期結果の先へ証拠を広げられます。 --- # 改善と再検証 失敗した段階から具体的な修正内容を決め、同じタスクをもう一度検証します。 出典: https://flovia.dev/docs/ja/improvement-loop/ ## 観測した失敗から修正対象を決める 評価の結果を、何を変えるか、なぜそれが有効そうか、どう確かめるかという判断につなげます。ダッシュボードの指摘から根拠を確認し、対象を絞って修正します。再検証の結果を見て、次の改善を決めます。 出発点は、観測した失敗と、それに影響し得るプロダクト側の変更対象です。Floviaは、チームのコーディングエージェントで実行できる修正プロンプトを生成します。修正案は、タスク、失敗した段階、再検証で確認すべき動作に結び付けられます。 | 観測した失敗 | 確認する箇所 | 再検証で確かめること | | --- | --- | --- | | 対象が現れない、または選ばれない | プロダクトの位置付け、ドキュメント、ランディングページ、llms.txt、候補の説明 | 定義した発見条件の下で、対象が現れる、または選ばれるか？ | | 操作を誤る | APIやMCPのツール名、説明、操作ごとの役割 | 許可した操作を正しく特定できるか？ | | 引数が無効 | パラメーターの意味、入力制約、具体的な使用例 | リクエストがスキーマと意味の検証を通過するか？ | | 結果が利用できない、または回答が不完全 | 応答仕様、必須フィールド、単位、結果の解釈方法 | 返されたデータで、すべての完了基準を満たせるか？ | これらは診断の出発点です。ページを変更しても、モデルがそのページを取得・利用するとは限りません。再検証では、エージェントへの情報の渡し方を維持するか、変える場合はその条件を明示します。 ## ダッシュボードで指摘から修正へ進む 専用ダッシュボードでは、評価の概要、根拠となる実行記録、修正ガイダンスをまとめて確認できます。以下は、顧客を識別できる情報を置き換えた実際のダッシュボードの抜粋です。数値は、画面に示した個別のテストの結果です。 この例では、コーディングエージェントに取引履歴を取得するコードを書かせ、ドキュメントを届ける方法を比較しています。CLAUDE.mdから説明を参照できるようにすると、対象APIを選ぶ結果は6回中0回から6回中6回になりました。これは、このタスクと条件で観測したAPI選択の結果です。 次に取り組む改善を選ぶ — 概要画面では、修正候補ごとに観測された変化と、その根拠となるテストを確認できます。まず詳しく調べる項目を選びます。 ![概要画面：修正候補と、選択中の項目の比較結果。](https://flovia.dev/docs/images/dashboard-overview.png) 概要画面：修正候補と、選択中の項目の比較結果。 指摘の内容を読む — 改善項目を開くと、エージェントが何につまずいたのか、どの変更が推奨されているのかを確認できます。この例では、起動時に読み込む指示ファイルからドキュメントへのリンクがなく、専用APIや登録方法が見つからないケースがありました。 ![指摘画面：見つからなかった導線、推奨する変更、証拠と実装用プロンプトへの入口。](https://flovia.dev/docs/images/dashboard-finding.png) 指摘画面：見つからなかった導線、推奨する変更、証拠と実装用プロンプトへの入口。 根拠を確認し、修正を準備する — 証拠画面で評価条件と実行記録を確認します。実装用プロンプトをコピーしてチームでレビューし、変更を反映します。リリース後に同じテストを再実行し、変更を採用するか、さらに修正するかを判断します。 ![証拠画面：説明への導線を変えた条件と、その前後の観測結果。](https://flovia.dev/docs/images/dashboard-evidence.png) 証拠画面：説明への導線を変えた条件と、その前後の観測結果。 ## ドキュメント改善の例 あるブロックチェーンデータAPIで、機能の選び方や使い方が伝わるようにドキュメントを更新しました。更新前と更新後の資料に基づくAIの回答を比較し、どの説明が改善し、どこに誤りが残るかを確認しました。 確認したのは、用途に合う機能を選べているか、正しい呼び出し先を示せているか、開発者側で必要な作業を説明できているかです。以下の各項目は、更新後の資料に基づく5回の回答を確認したものです。 | 確認した機能 | 変更前 | 変更後 | | --- | --- | --- | | トランザクションIDだけを取得 | 5回中0回。方法を特定できないか、別の用途向けの機能を案内 | 5回中5回、履歴取得機能でIDだけを取得する方法を説明 | | 取引履歴の取得方法の使い分け | 元の取引データの取得と、解析済みで読みやすい履歴の取得の違いを説明できず | 5回中5回、違いを説明。ただし4回は、元データの取得に使うAPI名を取り違え | | WebSocketによるリアルタイム監視 | 接続準備用のツールを呼べば監視が始まるのかが不明確 | 5回中5回、ツールは接続情報やサンプルコードを返すもので、監視処理は開発者側で動かす必要があると説明 | | サーバーでリアルタイムストリームを受信 | 接続情報の参照と、接続設定の生成を正しく区別できず | 5回中5回、接続設定を生成する機能を選び、接続自体は開発者側で確立すると説明 | | 優先手数料の見積もり・接続情報の取得 | 機能と呼び出し先の対応を誤り | 5回中5回、正しい呼び出し先を示した | 改善が見られたのは、取引履歴の取得方法の案内、リアルタイム配信の接続準備、優先手数料の見積もりなどの呼び出し先です。 開発者にとっては、誤った方法で実装を進めたり、接続の準備だけでサービスが動き始めると誤解したりすることの減少が期待できます。この比較で確認したのはAIの案内の改善であり、実装ミスや問い合わせ件数の減少は測定していません。 ここでの件数は、この比較で確認した回答の数であり、実APIの実行成功率や、他のタスク・モデルでの成功率を表すものではありません。次の再検証では、使い分けの説明とは別に、正しいAPI名を示せるかを個別に確認します。 ## 例：過去の為替レートを取得する操作を選びやすくする シナリオ設計で紹介した架空の為替レートAPIを使い、確認したいことから修正の判断までの流れを説明します。手順を示すための例であり、顧客の評価結果ではありません。 | ステップ | 進め方 | | --- | --- | | 問い | 今日のレートではなく、指定日のEURからUSDへのレートを取得できるか？ | | 評価 | ツール一覧と準備済みの応答を固定したうえでタスクを実行します。選んだ操作、通貨と日付の引数、最終回答を確認します。 | | 指摘 | 最新レートの操作を選んだとします。最初の失敗は操作の選択なので、二つの操作の説明を確認します。 | | 修正 | 過去のレートを取得する操作の用途を明記し、日付を指定する使用例を加えます。この比較では、スキーマと応答は変えません。 | | 再検証 | 同じタスクを同等の条件で再実行します。過去のレートの操作を選べるようになったか、回答まで正しく完了できたかを確認します。 | | 判断 | テストした動作が改善していれば、新しい説明を採用します。操作は正しく選べても日付の引数を間違えるなら、次は日付の指定方法を検証します。 | ## 修正プロンプトは検証できる形にする 修正プロンプトの例 · 架空の為替API ```text 観測した失敗：日付を指定した依頼に対し、エージェントが 最新レートの操作を選んでいる。 最新レートと過去のレートの違いが伝わるように操作の説明を修正する。 日付形式を記載し、日付を指定したEUR-to-USDの例を一つ追加する。 エンドポイントの動作とスキーマは変更しない。 合格条件：同じ日付付きタスクでget_historical_rateを選び、 正しい日付と通貨を指定する。続けて、返されたレートと日付を 最終回答で使っていることを確認する。 ``` チームが修正内容をレビューし、自社環境に実装します。Floviaは診断、修正ガイダンス、検証を提供し、変更と再検証結果を結び付けます。 ## 再検証の結果から次の行動を決める 変化した段階と最終結果を併せて読みます。一つの問題を解消すると、次の問題が見えることがあります。既に正しく動いている部分を保ちながら、次に直す箇所を選びます。 | 再検証で分かったこと | 次の行動 | | --- | --- | | 選択は改善したが、まだ違う操作が選ばれる | 分かりやすくなったプロダクトの説明は維持し、操作名・説明・使い分けを確認する | | 正しい操作を選ぶが、引数が不正 | パラメーターの意味を明確にし、タスクの制約を反映した使用例を追加する | | 結果は利用できるが、回答に必要な情報が足りない | 完了条件と対応する出力フィールドを確認し、その意味と回答での使い方を明確にする | | モデルやタスクによって結果が異なる、または欠測がある | 修正を選ぶ前に、該当グループと失敗記録を確認する。必要な範囲で比較を補う、または広げる | 過去の為替レートの例では、過去データ用の操作を選べれば、操作の選択ミスは解消します。その後の回答から日付が抜けていれば、完了段階の別の問題として、次の再検証条件にします。 - [完了判定の例を読む](https://flovia.dev/docs/ja/agent-funnel/): レート、通貨の方向、日付をそれぞれどう確認するかを見ます。 ## 同じ判断をもう一度検証する 1. 変更した成果物と、介入対象のフィールドを記録します。 2. タスク、要求するモデル、候補条件、実行経路、採点を比較可能な状態に保ちます。 3. 設計どおりに、修正した情報が実際に与えられる、または取得されることを確認します。 4. 段階別の結果と完了を、欠測やカバレッジとともに比較します。 5. 残っている失敗を基に、次の介入を定義します。 モデルの更新と測定期間も重要です。周辺条件が変わった場合は、比較の中で明示します。結果には、検証した段階で何が改善し、何が未解決のままかを示します。 --- # 技術FAQ シミュレーション、評価手法、現在の提供形態についてのよくある質問に答えます。 出典: https://flovia.dev/docs/ja/faq/ ## Floviaは具体的に何をシミュレーションしますか？ Floviaは、定義した条件の下で、エージェントがタスクに取り組む過程をシミュレーションします。対象は、候補の発見、プロバイダーの選択、操作の特定、有効な呼び出し、設定した経路での実行、結果の利用可能性、回答の完了です。タスク定義、ツール仕様、採点基準があるため、実行過程を調べ、実行間で比較できます。 ## 実際にモデルを呼び出していますか？ はい。Live LLM / Mock Toolの段階別評価では、指定したモデルのエンドポイントを実際に呼び出し、ツール実行は準備済みの応答で評価します。オフラインのパイプラインテストでは、モデル応答も準備済みのものに置き換えることがあります。結果を読む際は、モデル呼び出しの経路とツール実行の経路を必ず確認してください。この二つは別々に設定します。 ## シミュレーションの合格は実APIの動作を証明しますか？ いいえ。実際のAPI応答の代わりにあらかじめ用意したデータを使って評価する場合、確認できるのは、AIが正しい呼び出しを組み立て、そのデータをもとに適切に回答できるかどうかです。実際のAPIが正しく動作するかどうかは、APIに接続して別途テストする必要があります。 - [評価結果の適用範囲](https://flovia.dev/docs/ja/metrics-and-evidence/): 比較、実行、再検証の結果を、次の判断にどう使うか。 ## どのような技術的手法を使っていますか？ 評価エンジンは、タスクに基づく実験設計、バージョン管理された入出力仕様、段階的な関数呼び出し、決定的なスキーマ・意味検証、モデル補助の完了評価、条件を統制したペア型メタデータ実験、証拠の来歴管理を組み合わせます。対応する実験設計では、循環ラテン方格で候補位置を均衡化します。適用可能な指標には、プロンプト単位または意図単位のクラスターブートストラップ、ペア化したクラスターブートストラップを使います。各評価では、実際に使った手法と設定を明示します。 ## 評価に使う手法はどう選びますか？ 答えたい問いに合わせて組み合わせます。失敗箇所の診断にはタスクごとの条件検証と段階別の評価を使い、説明文の変更には条件を揃えたペア比較を使います。候補の提示順による影響を調べる実験ではラテン方格を、対応する指標の区間推定にはクラスターブートストラップを使います。各評価では、適用する手法と設定を実験計画に記録します。 ## 単に言及されたかを調べるのと、どう違いますか？ 言及の確認で分かるのは、プロダクトが現れたかどうかです。ファネルではさらに、選択されたか、正しい操作にたどり着いたか、有効な引数を指定したか、利用できるデータを得たか、タスクを完了したかを確認します。これにより、可視性が改善しても正しく利用されない場合に、どの変更が必要かを特定します。 ## メタデータA/Bで自然発見を測定できますか？ いいえ。固定候補のメタデータA/Bは、指定した候補への提示を統制した条件での動作を測定するもので、自然発見を示すものではありません。候補を与えない評価は別の問いに答えます。実際にウェブから取得されたと主張するには、その評価での取得の証拠が必要です。 ## Floviaはどう利用しますか？ 公開APIはありますか？ 最初の評価は無料です。30分の打ち合わせで、APIやMCPを使ってエージェントに完了してほしいタスクを決めます。Floviaが評価を実行し、専用ダッシュボードで最初の結果をお届けします。 Floviaの公式サイトにある評価依頼フォームから始められます。Floviaがチームと評価範囲を決め、結果、失敗分析、修正ガイダンス、再検証結果を、お客様専用の非公開ダッシュボードで提供します。現在、公開Flovia API、SDK、MCPサーバーはありません。 ## 複数ステップのワークフローを評価できますか？ PromptCaseでは、タスクに対して定義した操作の選択、引数、結果に基づく回答を評価します。複数の処理をまとめた操作も扱えますが、エージェントが独立した呼び出しを順に組み立てるワークフローは、このプロファイルの対象外です。評価したいワークフローに合う実行経路を、評価範囲を決める際に確認します。 - [実行環境と評価範囲](https://flovia.dev/docs/ja/simulation-engine/): モデル呼び出し、ツール応答、完了判定のつながりを確認できます。 ## 推奨された変更は誰が実装しますか？ お客様のポリシーに合わせて、修正の進め方を選べます。お客様のチームが推奨された変更をレビューし、自社環境に反映する方法に加え、EnterpriseではGitHub連携による半自動の修正フローも利用できます。GitHub連携の場合も、レビューとデプロイはお客様のチームが判断します。変更後はFloviaが再評価し、改善した点と次に取り組む課題を確認できます。