GoとローカルLLMでAIエージェントを作って学んだ判断と実行と再開の仕組み

GoとローカルLLMを使い、フォルダ内の資料を調べて質問に答える小さなAIエージェントを作成した。

ソースコードは local-agent-go に置いている。ローカルLLMの実行にtensai、処理の進行管理にTemporalを使う。

このサンプルでは、LLMが次の操作をJSONで選び、Goが検証して実行する。実行結果をLLMに渡して判断を繰り返し、回答まで進める。その途中でWorkerが停止しても、完了記録のある処理の結果を引き継いで続行できるよう、Temporalによる耐久実行(Durable Execution)を利用する。

本記事では、LLMの判断、ツールの実行、停止後の再開という3つの仕組みを、実装に沿って整理する。

資料を調べて答えるエージェントを作る

調査対象は、架空の「社内資料管理API」の資料である。構成を説明する architecture.md や、起動手順を説明する setup.md などのMarkdownファイルを用意した。

例えば、起動手順を調べる場合は次のように質問する。

./local-agent-go -question '資料に書かれた社内資料管理APIの起動手順とヘルスチェック方法を教えて'

実際の実行では、次の回答が返った。以下の実行例では、CLIが表示するWorkflow ID、Run ID、待機ログを省き、回答本文をそのまま掲載する。回答中の「参照した資料・ツール」もプログラムの出力である。

社内資料管理APIの起動手順は以下の通りです。
- PostgreSQLを起動し、接続可能になるまで待ちます。 (`docker compose up -d postgres`)
- マイグレーションを実行します。 (`go run ./cmd/migrate`)
- APIを起動します。 (`go run ./cmd/api`)
社内資料管理APIのヘルスチェックは以下の通りです。
- `GET http://localhost:9090/healthz`

参照した資料・ツール:architecture.md, setup.md

PostgreSQLの起動、マイグレーション、APIの起動という順序と、ヘルスチェックのURLが返った。回答には、参照先として architecture.md と setup.md が示されている。読むファイルや順序はLLMが選ぶ。

資料中のAPIやデータベースは、架空のプロジェクトの説明である。エージェントの実行には、それらを起動する必要はない。

質問の書き方によって返る結果が変わった

次に、同じ起動手順の質問から「資料に書かれた」を外して実行した。

./local-agent-go -id recovery-demo-2 -question '社内資料管理APIの起動手順とヘルスチェック方法を教えて'

返ってきた回答は次のとおり。

社内資料管理APIの起動手順やヘルスチェック方法についての情報は、提供されたエビデンスから得られません。エビデンスには、ファイルの一覧や「こんにちは」というメッセージが含まれています。具体的な手順やヘルスチェック方法を知るためには、関連するAPIやドキュメントを確認する必要があります。

参照した資料・ツール:list_files, say_hello

起動手順を聞いているが、回答はファイル一覧と挨拶のメッセージに言及している。参照先として表示されたのも list_files, say_hello であり、資料ファイルの名前はない。必要な情報を調べて回答する目的を達成できなかった。

続けて、同じコマンドの質問に「資料に書かれた」を戻した。

./local-agent-go -id recovery-demo-2 -question '資料に書かれた社内資料管理APIの起動手順とヘルスチェック方法を教えて'

この実行では、先ほど掲載した起動手順とヘルスチェックの回答が再び返った。表示された参照先も architecture.md, setup.md だった。質問以外のコマンド引数を揃えた実行でも、結果に違いが出た。

今回記録した起動手順の質問を整理すると、次のようになる。

質問の条件記録した回数回答の結果
「資料に書かれた」あり2回2回とも起動手順とヘルスチェックを回答
「資料に書かれた」なし・待機指定あり1回必要な情報が得られないと回答
「資料に書かれた」なし・待機指定なし1回必要な情報が得られないと回答

情報源を明示する語句が、資料を参照する操作を選ぶ手がかりになった可能性がある。ただし、少数の実行例であり、この語句だけが原因だとは断定できない。モデルやWorkerの状態を固定して多数回比較した結果ではないため、成功率を示すものでもない。

これらは最終回答に表示された参照先の比較である。実際にどのツールをどの順序で実行したかを確定するには、WorkerログやTemporalの履歴と照合する必要がある。同じWorkflow IDを使った後続の実行もRun IDは異なっており、同一Runの結果を再表示した記録ではない。

資料にない情報を聞いた場合

./local-agent-go -question '社内資料管理APIの本番環境のURLと認証方式を教えて。資料に記載がなければ、その旨を答えて'
社内の資料管理APIの本番環境のURLや認証方式が記載されているファイルは見つかりませんでした。ただし、見つかったファイルにはURLや認証方式の情報は含まれていません。

参照した資料・ツール:list_files

この回答では、参照先に list_files だけが表示された。ファイル一覧の取得だけでは、本文に情報がないとは判断できない。この出力を「資料を調べて記載がないことを確認できた」成功例として扱うことはできない。

「資料に記載がなければ」と指示するだけで、必要な資料を十分に読むとは限らない。出力形式の検証に加え、回答に至るまでに何を観測したかも確認する必要がある。

LLMが操作を選びGoが実行する

LLMが選べる操作は、次の4つに絞った。

操作役割
list_files指定したディレクトリのファイル一覧を取得する
read_file指定した資料ファイルを読む
say_hello設定済みのローカルAPIに GET /hello を送る
finish最終回答を返して終了する

今回の実装では、操作を表すJSONをLLMに返させる。モデルのネイティブなtool_calls機能は使っていない。

資料を読む操作は、次のJSONで表す。

{"action":"read_file","path":"setup.md"}

Go側では、この出力を次の構造体で受け取る。

type Decision struct {
    Action string `json:"action"`
    Path   string `json:"path,omitempty"`
    Answer string `json:"answer,omitempty"`
}

read_file が選ばれたら、Goがファイルを読む。その内容を会話履歴に追加し、再びLLMに次の操作を問い合わせる。必要な情報が集まれば、LLMは finish と回答文を返す。

処理の流れは次のとおり。

図は、操作の選択から実行、回答までの流れを示している。不正なJSONへの修正要求や、API結果を直接返す分岐は後述する。

LLMは次に何をするかを選び、Goは用意した処理を実行する。この構造で、判断と実行の役割を分けている。

LLMが返したJSONを検証してから実行する

LLMの出力は、まず parseDecision で検証する。

この関数では、JSONとして読み取れることに加え、未知のフィールドが含まれていないこと、後ろに別のJSONや説明が続いていないことも確認する。操作名は4つの許可済みの名前と照合し、ファイル操作にはパス、finish には空でない回答を要求する。

例えば、次の出力はJSONとしては正しいが、許可されていない操作なので拒否する。

{"action":"delete_file","path":"setup.md"}

ファイルのパスも検証する。資料ルートからの相対パスを使い、隠しパスや .. による移動などは受け付けない。

最初の判断で、ツールを使わずに finish を返した場合も拒否する。ただし、この条件で確認できるのは、ツールの観測結果が先にあることまでである。回答が資料に正確に裏づけられているかは、別途確認する必要がある。

出力が不正だった場合、Decide はその出力とエラーの内容を履歴に追加し、正しいJSONを返すようLLMに指示する。初回を含め最大3回、全体で4分以内に収める。

修正できなければ、形式エラーとして終了し、同じ入力に対するTemporalの自動再試行も打ち切る。通信障害などに対する再試行とは、扱いを分けている。

プロンプトで出力形式を伝えたうえで、実行条件をGo側にも書く。操作名や必要な値の検証を通過した出力だけを、実際の処理につなぐ。

ツールが扱える範囲をコードで決める

ファイル読み取りには os.Root を使い、Worker起動時に指定した資料フォルダの中に制限する。読み取れる対象にも、次の条件を設けた。

  • UTF-8の .md と .txt を対象にする
  • 1ファイルは8 KiB以下にする
  • 一覧取得は1ディレクトリ200エントリ以下にする
  • 隠しパスやシンボリックリンクを拒否する

このサンプルには、ファイルへの書き込みやシェル実行の機能はない。資料に起動コマンドが書かれていても、それを実行するツールは用意していない。

ファイルが見つからない場合などは、操作上のエラーを観測結果としてLLMに返す。LLMはその結果を受けて、別のファイルを選び直せる。

LLMには資料の選択を任せ、アクセス範囲や読み取り条件はコードで固定する。

Temporalで実行履歴と再試行を管理する

Temporalは、耐久実行(Durable Execution)を実現する基盤である。処理の進行状況を実行履歴として永続化し、Workerが停止しても、履歴から状態を復元して処理を再開できる。一時的な通信障害などには、設定した方針に従って再試行する。

再試行の上限に達した場合や、再試行できないエラーが発生した場合は、Workflow側で失敗を処理する必要がある。今回のサンプルでは、そのエラーを受けてWorkflowを失敗として終了する。

判断と実行のループは、TemporalのWorkflowである Investigate に実装した。外部とのやり取りはActivityに分けている。

処理Temporal上の役割
Investigate判断とツール実行の順序、終了条件を管理するWorkflow
DecideローカルLLMをHTTPで呼び出すActivity
Read資料の一覧取得や読み取りを行うActivity
SayHelloローカルAPIを呼び出すActivity

Workflowは、Activityの結果を受け取りながら次の処理を決める。LLM呼び出しやファイル読み取りは、Activity側で行う。

この分離は、停止後の再開にも関係する。Workerが再起動すると、Temporalは実行履歴を再生し、完了記録のあるActivityには記録済みの結果を使う。その結果から、会話履歴と進行位置を組み立て直す。

例えば、資料を読むActivityの完了が記録されていれば、履歴の再生時にはその読み取り結果を使う。完了記録のない途中のActivityは、タイムアウト後に再実行される場合がある。

そのため、Temporalを使う場合も、外部APIが複数回呼ばれる可能性を考える必要がある。更新系の操作を追加するなら、同じ依頼を繰り返しても重複処理にならない設計が必要になる。

今回のコードでは、Activityの初回実行を含めた最大試行回数を3回に設定した。操作を選ぶループは既定で最大10ステップとし、終了を表す finish も1ステップに数える。各ステップの Decide 内では、形式修正を含めてLLMを最大3回呼び出す。通信などの失敗に対するActivityの再試行と、操作を選ぶループ、出力形式の修正は、それぞれに上限を設けている。

Workerを止めて再開の仕組みを確かめる

復旧の挙動を確認するため、ツール実行後に待機時間を入れるオプションを用意した。Temporalとtensai、Workerを起動した状態で、次のように実行する。

./local-agent-go -id recovery-demo-1 -delay 30s -question '社内資料管理APIの構成と起動方法は?'

Temporal UIでActivityの完了とTimer待機を確認し、Workerを停止する。その後、同じ資料、モデル、Task Queueを指定してWorkerを再起動する。

確認するのは、完了記録のある処理の結果が再利用され、残りの処理が進むことである。質問CLIも停止した場合は、Workflow IDを指定して結果を取得できる。

./local-agent-go -mode result -id recovery-demo-1

この確認には、Temporal Serverが動き続けていること、または同じDBファイルを使って再起動することが必要になる。起動手順の詳細は、リポジトリのREADMEにまとめている。

前述の比較では -delay 30s を指定した実行もあるが、CLIの待機表示だけでは、Workerの停止と再起動や、完了結果の再利用を確認できない。耐久実行の復旧確認には、停止前後のActivityやTimerの履歴を使う。また、Workflowが続行できることと、LLMが適切な資料を選んで回答できることは、それぞれ確認する必要がある。

実行中のWorkflowに対してコードを変更すると、既存履歴との互換性が問題になる。このサンプルでは、挨拶APIの結果を直接返す変更に対応するため、workflow.GetVersion による分岐を入れている。

挨拶APIの呼び出しと回答形式を比べる

say_hello は、ローカルAPIに GET /hello を送るツールである。呼び出しを依頼したときのCLI出力も確認した。

./local-agent-go -question 'あいさつAPI実行して'
このAPIは「こんにちは、世界!」というメッセージを出力しました。

参照した資料・ツール:say_hello

この実行では、日本語の説明文が返った。次に、実行結果をJSONでそのまま返すよう指定した。

./local-agent-go -question 'あいさつAPIの実行結果をJSONでそのままください'
このAPIの実行結果は以下のJSON形式で得られました。
- {"message": "Hello, World!"}
この結果から、あいさつAPIが実行された結果は "Hello, World!" です。

参照した資料・ツール:say_hello

JSONオブジェクトは含まれているが、前後に説明文、箇条書き、参照先が付いている。出力全体をJSONパーサーに渡せる形式にはなっていない。「JSONでそのまま」と依頼しても、この実行では出力形式まで守られなかった。

操作選択用のJSONと、利用者に返す最終回答は別の出力である。操作のJSONをGo側で検証していても、最終回答が指定どおりのJSONになることまでは保証しない。

実行結果とソースコードの違い

本記事末尾で参照しているコミットには、新しいWorkflowで say_hello が成功し、空でない message を取得したら、その値を直接返す処理がある。その経路では、取得後にLLMで文章を生成しない。

一方、今回の実行結果には説明文や参照先が付いており、この直接返却の動作と一致していない。実行時のバイナリやWorkerが参照コミットと一致していたかは、このログからは確認できない。上記は観測したCLI出力として掲載し、直接返却の実証とは分けて扱う。

APIの値を変更せず返したい場合は、取得した値をコード側で返却する。最終出力全体をJSONにしたい場合も、返すオブジェクトをコード側で組み立ててシリアライズすることで、形式を制御できる。

実装を通して整理できた役割分担

今回のサンプルでは、LLM、Go、Temporalにそれぞれ役割を持たせた。

LLMは、質問と観測結果をもとに次の操作を選ぶ。Goは、その選択を検証し、許可したツールを実行する。Temporalは、処理の順序、実行履歴、再試行を管理する。

この役割分担をコードで追うと、操作の選択から回答までの流れを具体的な処理として確認できる。出力の検証、終了条件、停止した処理の再開も、それぞれ実装する必要がある。

現在の実装は、小さなテキスト資料を対象にした学習用の構成である。PDFやベクトル検索、複数利用者向けの権限制御は含んでいない。質問、文書の読み取り結果、回答はTemporalの履歴にも保存される。

今回の実行では、質問で情報源を明示するかどうかによって、回答と表示された参照先が変わった。資料を十分に読んだか、質問に合うツールを選んだか、最終回答が指定した形式かも、実行結果から確認する必要がある。Temporalによる耐久実行に加え、LLMの判断と回答の品質をどう確かめるかが、このサンプルで見えた課題である。

ソースコード

今回の記事で使ったソースコードは、以下のリポジトリに置いている。

GitHub – taako-502/local-agent-go: Go …

GitHub – taako-502/local-agent-go: Go …

Go + Temporal + Local LLMでAIエージェントのサンプルプログラム. Contribute to taako-502/local-agent-go development by creating an account …

Go + Temporal + Local LLMでAIエージェントのサンプルプログラム. Contribute to taako-502/local-agent-go development by creating an account …

起動手順と実装の詳細は、以下を参照。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です