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 と回答文を返す。
処理の流れは次のとおり。
flowchart TD
A["質問と履歴を渡す"] --> B["LLMが操作を選ぶ"]
B --> C["GoがJSONを検証する"]
C --> D{"操作"}
D -->|資料やAPI| E["ツールを実行する"]
E --> F["結果を履歴に追加する"]
F --> A
D -->|finish| G["回答して終了する"]図は、操作の選択から実行、回答までの流れを示している。不正な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 …
起動手順と実装の詳細は、以下を参照。

コメントを残す