初めてのAIエージェントを作る — 最小構成で試した実装記録

最小構成の設計 — ツール2つとステップ上限から始めた

最初に決めたのは、できるだけ小さく作ることでした。用意したツールは、指定フォルダ内のファイル一覧を返す list_files と、指定したファイルの中身を返す read_file の2つだけです。ファイルを書き換えるツールはあえて含めず、最終的な要約はメッセージとして返すだけにとどめました。これが最初のガードレールになります。

システムプロンプトには「フォルダ内のテキストファイルを読み、内容をmarkdown形式で要約すること」という指示のほか、ツールの使い方と終了条件を明記しました。効果的なプロンプトの構造で扱った、指示・文脈・制約を分けて書くという原則は、この種のエージェント用システムプロンプトでもそのまま有効で、制約条件をあいまいに書いた箇所ほど後述のループにつながりました。ステップ数の上限は6に設定し、それを超えたら未完了のまま処理を打ち切る仕様にしました。

最初の実行 — 動いた部分

5つのテキストファイルが入ったフォルダで試したところ、エージェントはlist_filesでファイル名を確認し、拡張子からテキストファイルのみを選んでread_fileを呼び、4ステップで要約を完成させました。フォルダ内に対象となるファイルが1つも見つからなかった別のケースでは、存在しないファイル名を推測して呼び出すのではなく、「対象ファイルが見つかりません」という応答を返して処理を終了しました。これは本稿執筆時点でのモデルの挙動であり、モデルやバージョンによって結果は異なりますが、少なくとも今回の構成では、情報が不足している状況を無理に埋めようとしない振る舞いが確認できました。

ループした場面 — 同じツールを呼び出し続けた失敗

問題が起きたのは、対象ファイルの1つが空ファイルだったケースです。read_fileはこのファイルに対してエラーメッセージを返しましたが、エージェントはそのエラーを「内容が読み取れなかったので条件を変えて再試行すべき信号」だと解釈し、引数をわずかに変えながらread_fileを繰り返し呼び出しました。ステップ上限の6回に達しても要約は完成せず、未完了のまま処理が打ち切られました。

原因をたどると、システムプロンプトの中でツールのエラー出力と正常な出力を区別する記述が抜けていたことに行き着きました。モデルにとっては、ツールから返ってきた文字列はすべて「解釈すべきデータ」であり、それがエラーを示すものだという前提を明示しない限り、区別する手がかりがありません。対策として、エラー出力の先頭に「ERROR:」という接頭辞を付ける形式をツール側で統一し、「ERROR:から始まる結果を受け取った場合、同じツールを条件を変えずに2回以上連続で呼び出さない」という指示をシステムプロンプトに追加したところ、同様のケースでは1回の失敗を報告した時点で処理が終了するようになりました。

効いたガードレール — ツール制限・ステップ上限・人による確認

今回の実装で実際に効果があったのは、モデルの精度を上げる工夫ではなく、失敗の被害を小さく抑える3つの制約でした。1つ目はツールを読み取り専用の2つに絞り、シェル実行やファイル削除のような操作を最初から与えなかったことです。誤った判断をしても被害の範囲がフォルダの中身を誤読する程度にとどまります。2つ目はステップ数の上限で、これによって無限に近いループが「気づかれない停止」ではなく「明示的な未完了」という見える形の失敗になりました。

3つ目は、状態を変更する操作の前に人の確認を挟む仕組みです。今回の構成には書き込み系のツールを含めませんでしたが、要約結果をファイルに保存するwrite_summaryのようなツールを仮に追加する場合を想定し、エージェントが書き込む内容を提案した時点で処理を一時停止し、操作者が内容を確認してから実行を許可する流れを別途検証しました。読み取り専用の範囲を出た瞬間に人の確認を必須にするという設計は、規模を広げる際の前提になると考えています。

とはいえ最小構成にも限界がある

もっとも、今回のようなツール2つ・ステップ上限6回という構成がうまくいったのは、タスク自体が単純で、失敗しても被害が小さいものだったからという面が大きいです。AIエージェントの仕組みで触れたとおり、ステップ数が増えツールの種類が増えるほど、誤りが積み重なるリスクは指数的に大きくなっていきます。ツールを何十個も扱う、あるいは数十ステップにわたるような複雑なタスクでは、単純な上限設定だけでは足りず、タスクごとの評価基準やログの取得、場合によっては別のモデルによる出力チェックといった追加の仕組みが必要になるはずです。

次に試すべきこと — 何を測るべきか

今回の記録から見えてきたのは、エージェントを大きくする前に測るべき指標がいくつかあるということです。タスクが完了するまでの平均ステップ数、エラーが発生した際にループへ入らず正しく回復できた割合、人による確認が必要になった頻度などは、いずれも今回のような小さな構成のうちに基準値を取っておくべき数字です。次にツールの数を増やす、あるいはステップ上限を引き上げる判断は、この基準値からどれだけ悪化したかを見てから決めるほうが、感覚だけで自律性を広げるより安全だと考えています。