> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/agent-ops/tool-execution-records.md).
# ツール実行記録
## 概要
ツール実行記録では、AI アシスタントが外部ツールを呼び出した完全な履歴を追跡できます。API 呼び出し、データベースクエリ、Web クローリングなどの操作が含まれます。AI アシスタントが対話の範囲を超えるタスクを実行する必要がある場合は、ツールを通じてそれを完遂します。ツール実行記録は、ツールの利用状況を把握し、実行失敗の原因を特定し、ツール設定を最適化するのに役立ちます。
完全な実行記録を活用することで、ツールの失敗原因を 5 分以内に特定でき、問題切り分けにかかる時間を 80% 短縮し、AI アシスタントが高度な機能を安定して提供できるようにします。
## 機能の特長
ツール実行記録機能を利用すると、次のことが可能になります。
### 📋 **実行履歴を完全に記録**
システムはツールが呼び出されるたびに、入力パラメータ、実行結果、所要時間、成功または失敗のステータスを自動的に記録します。
* **利用シーン**：EC プラットフォームの注文照会ツールが毎日 500 回呼び出されており、成功率とレスポンス時間を追跡する必要がある
* **実際の効果**：10% のクエリがタイムアウトで失敗していることを発見し、タイムアウト設定を調整した結果、成功率が 98% まで向上した
### 🔍 **失敗原因を素早く特定**
ツールの実行が失敗した場合、システムは詳細なエラーメッセージを記録し、どこに問題があるのかを素早く把握できるようにします。
* **利用シーン**：天気照会 API が突然頻繁に失敗するようになり、原因を素早く突き止める必要がある
* **実際の効果**：エラー記録から API キーの有効期限切れを発見し、5 分以内に更新を完了してサービスを復旧した
### 📊 **ツールの利用状況を統計**
各ツールの呼び出し回数、成功率、平均実行時間などの統計情報を確認できます。
* **利用シーン**：企業が 10 個のツールを設定しており、どのツールが最も頻繁に使われ、どのツールに最も問題が多いかを把握したい
* **実際の効果**：3 個のツールが一度も使われていないことを発見し、削除することでシステムの複雑さを低減し、他のツールのレスポンス速度が 15% 向上した
### 🎯 **ツール設定を最適化**
実行記録の分析に基づいて、ツールのパラメータ調整、呼び出しロジックの最適化、エラー処理の改善を行います。
* **利用シーン**：データベースクエリツールが、クエリ範囲が大きすぎてしばしばタイムアウトする
* **実際の効果**：記録分析に基づいてクエリ制限を調整し、実行時間が平均 8 秒から 3 秒に短縮された
## ツールタイプの説明
MaiAgent は複数のツールタイプをサポートしており、ツール実行記録はすべてのタイプの実行状況を追跡します。
### API ツール
外部 API を呼び出してリアルタイムデータを取得します。たとえば天気照会、為替照会、在庫照会などです。
**よくある実行上の問題**：
* API キーの有効期限切れまたは無効
* リクエストパラメータの形式エラー
* API サービスのタイムアウトまたは無応答
* API 呼び出し回数の上限超過
### Text-to-SQL ツール
自然言語の質問を SQL クエリに変換し、データベースからデータを取得します。
**よくある実行上の問題**：
* SQL 構文エラー
* クエリ範囲が大きすぎることによるタイムアウト
* データベース接続の失敗
* 権限不足により特定のテーブルにアクセスできない
### クローラーツール
指定した Web サイトからリアルタイムの情報を取得します。たとえば最新ニュースや商品価格などです。
**よくある実行上の問題**：
* 対象 Web サイトに接続できない
* Web ページ構造の変更による解析の失敗
* 対象 Web サイトによるブロックまたはレート制限
* クローリングのタイムアウト
### カスタムツール
企業が独自に開発した特定機能のツールです。たとえば注文処理や会員認証などです。
**よくある実行上の問題**：
* 内部サービスの異常
* パラメータ検証の失敗
* ビジネスロジックのエラー
* システム連携の問題
## 利用手順
### 手順 1：ツール実行記録にアクセスする
1. 管理画面に入り、左側メニューの AgentOps → ツール実行記録 をクリックします
2. 直近のツール実行記録の一覧を確認します
ツール実行記録の一覧ページ
### 手順 2：記録を絞り込んで確認する
絞り込み条件を使って、注目すべき実行記録を見つけます。
1. **期間**：
* 本日、直近 7 日、直近 30 日
* または開始日と終了日をカスタム指定
2. **ツールタイプ**：
* すべてのツール
* API ツール
* Text-to-SQL
* クローラーツール
* カスタムツール
3. **実行ステータス**：
* すべて
* 成功
* 失敗
* 実行中
4. **特定のツール**：
* ドロップダウンメニューから特定のツール名を選択
5. 「絞り込みを適用」をクリックして、条件に一致する記録を確認します
{% hint style="info" %}
**優先的に確認すべき項目**
以下を優先的に確認することをおすすめします。
1. 実行に失敗した記録
2. 実行時間が 10 秒を超えた記録
3. 高頻度で使われているツールの実行状況
{% endhint %}
### 手順 3：実行詳細を確認する
1. 記録の一覧でいずれかの記録をクリックします
2. 詳細情報を展開すると、次の内容が含まれます。
**基本情報**：
* ツール名
* 実行時刻（いつ呼び出されたか）
* 実行所要時間（何秒かかったか）
* 実行ステータス（成功／失敗）
**入力パラメータ**：
* AI がツールに渡したパラメータの内容
* パラメータが正しいかどうかを確認可能
**実行結果**：
* ツールが返した完全な結果
* 成功時は取得したデータを表示
* 失敗時はエラーメッセージを表示
**関連する対話**：
* このツール呼び出しを引き起こした対話記録
* ユーザーの元の質問を追跡可能
**エラーメッセージ**（ある場合）：
* 詳細なエラーの説明
* エラーコードまたは例外の種類
* スタックトレース情報（該当する場合）
### 手順 4：失敗原因を分析する
実行に失敗した記録を見つけた場合は、以下の手順で分析できます。
1. **エラーメッセージを確認する**：
* 詳細なエラーの説明を読む
* 設定の問題、権限の問題、サービスの異常のいずれかを識別する
2. **入力パラメータを確認する**：
* AI が渡したパラメータが正しいかを確認する
* パラメータの形式がツールの要件を満たしているか確認する
3. **関連する対話を確認する**：
* ユーザーがどのような質問をしたのかを把握する
* 特定の質問タイプが失敗を引き起こしていないか判断する
4. **成功事例と比較する**：
* 同じツールの成功した実行記録を見つける
* 成功事例と失敗事例の違いを比較する
### 手順 5：ツール設定を最適化する
実行記録の分析結果に基づいて、改善策を講じます。
1. **ツール設定を更新する**：
* 誤った API キーや接続情報を修正する
* タイムアウト時間の設定を調整する
* クエリパラメータや制限条件を最適化する
2. **AI プロンプトを調整する**：
* パラメータが頻繁に誤っている場合は、プロンプトに明確なガイドを加える
* ツールの正しい使い方とパラメータ形式を説明する
3. **エラー処理を改善する**：
* よくあるエラー状況に対して、わかりやすいエラーメッセージを加える
* 自動リトライの仕組みを設定する
4. **不要なツールを削除する**：
* 長期間使われていないツールは、設定を簡素化するために削除を検討する
### 手順 6：実行記録をエクスポートする
1. ツール実行記録のページで「エクスポート」ボタンをクリックします
2. エクスポート形式（CSV または Excel）を選択します
3. 期間と絞り込み条件を選択します
4. レポートをダウンロードして、さらなる分析や保管に利用します
{% hint style="info" %}
エクスポートした記録は、以下に活用できます。
* 詳細なデータ分析とトレンド追跡
* 技術チームへの問題報告
* ツール利用効率の定期的な見直し
* コンプライアンス監査と記録保存
{% endhint %}
## 利用シーン
### シーン 1：ツール障害の診断
**状況**：EC プラットフォームの在庫照会ツールが突然大量に失敗し始め、カスタマーサポートが顧客に商品在庫を照会できなくなった。
**操作方法**：
1. ツール実行記録に入り、「在庫照会ツール」＋「失敗」で絞り込む
2. 過去 2 時間で 50 件の失敗記録があることを発見する
3. 失敗記録のエラーメッセージを確認する：「データベース接続タイムアウト」
4. データベースサービスの状態を確認し、データベースがメンテナンス中であることを発見する
5. 一時的にツールを無効化し、カスタマーサポートに手動照会へ切り替えるよう通知する
6. データベース復旧後に再度有効化し、成功率が正常に戻ることを監視する
**定量的な効果**：
* 5 分以内に問題の根本原因を特定
* 技術チームが数時間かけて切り分けする事態を回避
* カスタマーサポートにバックアップ手段への切り替えを速やかに通知し、顧客の待ち時間を削減
### シーン 2：ツール性能の最適化
**状況**：注文照会ツールがしばしば遅く、対話体験に影響している。
**操作方法**：
1. 直近 30 日の注文照会ツールの実行記録をエクスポートする
2. 実行時間の分布を分析し、次のことを発見する。
* 平均実行時間 7.5 秒
* 25% のクエリが 10 秒を超過
* 最長で 18 秒
3. 遅いクエリの入力パラメータを確認し、その多くが「直近 1 年のすべての注文」を照会していることを発見する
4. ツール設定を最適化する：
* クエリ範囲を直近 3 か月に制限
* ページング機構を追加し、1 回あたり最大 20 件を返す
5. 最適化後、平均実行時間が 3.2 秒に短縮された
**定量的な効果**：
* 実行時間が 57% 短縮（7.5 秒 → 3.2 秒）
* 10 秒を超えるクエリが 25% から 5% に減少
* 対話体験が大幅に改善し、顧客満足度が向上
### シーン 3：未使用ツールの発見
**状況**：企業が AI アシスタントに 12 個のツールを設定しており、設定を簡素化するために実際の利用状況を把握したい。
**操作方法**：
1. 直近 90 日のすべてのツール実行記録をエクスポートする
2. 各ツールの呼び出し回数を集計する。
* 注文照会：1,500 回
* 会員照会：800 回
* プロモーション照会：300 回
* 商品仕様照会：200 回
* その他 8 個のツール：0 回
3. 未使用ツールの設定を確認し、次のことを発見する。
* 一部のツールは定義が不明確で、AI がいつ使うべきか判断できない
* 一部のツールは機能が重複している
* 一部のツールはすでに古くなっている
4. 6 個の未使用ツールを削除し、利用率の低い 2 個のツールの説明を最適化する
**定量的な効果**：
* 設定を簡素化し、AI がツールを選択する精度が 20% 向上
* システムのレスポンス速度が 10% 向上（ツール選択の判断時間を削減）
* 保守コストを低減
### シーン 4：API 使用量の監視
**状況**：企業がサードパーティの天気 API を利用しており、月ごとに呼び出し回数の上限があるため、超過を避けるために使用量を監視する必要がある。
**操作方法**：
1. 毎週月曜日に天気照会ツールの実行記録をエクスポートする
2. 呼び出し回数の推移を集計する。
* 第 1 週：320 回
* 第 2 週：450 回
* 第 3 週：680 回
* 第 4 週：900 回と予測（月の上限 2,000 回）
3. 呼び出し量が急増していることを発見し、原因を分析する。
* 顧客が天気を尋ねる頻度が増加
* 一部に不要な重複クエリがある
4. 対策を講じる：
* キャッシュ機構を追加し、同じ都市は 1 時間以内は重複して照会しない
* プロンプトを最適化し、AI が天気ツールに過度に依存しないようにする
5. 最適化後、週あたりの呼び出しが 400 回に減少し、上限超過を確実に回避
**定量的な効果**：
* API の上限超過によるサービス停止を回避
* API 呼び出しコストを 40% 削減
* サービス品質を維持しつつコストを抑制
## よくある質問
### Q: ツール実行記録はどのくらい保持されますか？
A: システムはデフォルトで 3 か月分のツール実行記録を保持します。重要なデータは定期的にエクスポートして、長期保存と分析を行うことをおすすめします。より長い保持期間が必要な場合は、カスタマーサポートに連絡してプランをアップグレードしてください。
### Q: なぜツールの実行は失敗しているのに、対話は正常に見えるのですか？
A: ツールの実行が失敗した場合、AI アシスタントは次のような対応をすることがあります。
1. ユーザーに「現在照会できません。しばらくしてから再度お試しください」と伝える
2. ナレッジベースの情報を使って回答する（関連する内容がある場合）
3. ユーザーにさらに情報を提供してもらってから再試行する
対話は続いていても、機能は制限されています。実行記録を通じて失敗原因を追跡して修正し、ツールが安定して動作するようにすることをおすすめします。
### Q: ツールの実行失敗率を下げるにはどうすればよいですか？
以下の観点から最適化することをおすすめします。
**設定面**：
* API キーやデータベース接続などの設定が正しいことを確認する
* 適切なタイムアウト時間を設定する（10〜15 秒を推奨）
* エラーリトライの仕組みを加える
**プロンプト面**：
* ツールの使用タイミングとパラメータ形式を明確に説明する
* AI が正しくツールを呼び出せるように例を加える
**監視面**：
* 実行記録を定期的に確認する
* 問題を速やかに発見して修正する
* 成功率の推移を追跡する
### Q: 実行記録の入力パラメータに機密データが含まれる場合はどうすればよいですか？
A: システムは一般的な機密データ（パスワードやキーなど）を自動的にマスクします。お使いのツールが他の機密データ（顧客の個人情報など）を扱う場合は、以下をおすすめします。
1. ツール設定で「パラメータマスク」機能を有効にする
2. 実行記録の閲覧権限を制御し、必要な担当者のみに権限を付与する
3. 期限切れの実行記録を定期的に削除する
### Q: 失敗したツール呼び出しを再実行できますか？
A: 現在、システムは履歴記録を直接再実行することをサポートしていません。ツールをテストする必要がある場合は、以下をおすすめします。
1. 対話プラットフォームで直接質問してツール呼び出しを発生させる
2. ツールのテスト機能を利用する（提供されている場合）
3. 問題を修正したうえで、実際のユーザーによるトリガーを待つ
### Q: ある対話がどのツールを呼び出したかを確認するにはどうすればよいですか？
A: 2 つの方法があります。
1. **対話記録から確認する**：対話の詳細に、その対話が呼び出したすべてのツールが表示されます
2. **ツール記録から逆引きする**：ツール実行記録で「関連する対話」のリンクをクリックします
## ベストプラクティス
### 定期チェックの推奨事項
* **毎日のチェック**：過去 24 時間の失敗記録を確認し、重要なツールが正常に動作していることを確認する
* **毎週の見直し**：各ツールの呼び出し回数と成功率を集計し、最適化が必要な項目を特定する
* **毎月の分析**：完全なレポートをエクスポートし、長期的なトレンドと利用パターンを分析する
### アラート設定の推奨事項
以下のアラートを設定することをおすすめします（システムが対応している場合）。
* あるツールが 1 時間以内に 10 回を超えて失敗した
* あるツールの成功率が 80% を下回った
* あるツールの平均実行時間が 10 秒を超えた
* あるツールが 7 日以上使われていない（必要かどうかを確認する）
### ドキュメント記録の推奨事項
各ツールについて利用ドキュメントを作成し、次の内容を記録します。
* ツールの用途と適用シーン
* 入力パラメータの説明と例
* 想定される出力形式
* よくあるエラーと解決方法
* 最適化の履歴記録
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/agent-ops/tool-execution-records.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.