Integuru v0：ブラウザのHARから内部APIを逆算し、Pythonコードを生成するエージェント

公式APIの空白を、ブラウザの通信記録で埋める

Integuru v0が対象にするのは、公式のAPIドキュメントが存在しない、あるいは存在しても目的の操作をカバーしていないプラットフォームである。たとえば公共料金の請求書をダウンロードしたい場合、ブラウザ上では数クリックで済むが、それを自動化する公式の手段がないことがある。READMEはこの例をそのまま使っており、目的の操作をブラウザで一度実行し、その通信記録からエンドポイントを特定するという流れを説明している。想定している利用者は、対象サービスの利用規約と自分のアカウントの範囲内で、繰り返し作業を自動化したい開発者である。RPAツールのように画面の座標を操作するのではなく、HTTPリクエストのレベルで再現する点が特徴で、画面のレイアウト変更に比較的強い代わりに、リクエストの構造変更には弱い。

依存関係グラフを上流へたどる再帰的な分解

仕組みの中心は、リクエスト同士の依存関係をグラフとして組み立てる処理である。READMEの例では、請求書ダウンロードのリクエストURLが accountId と userId という動的な値を含んでおり、これらは別のリクエストから取得される。エージェントはその値の出所を探し、ダウンロードのリクエストをそれらのリクエストに依存させる。この探索を、確認中のリクエストが認証Cookie以外に何も必要としなくなるまで繰り返す。その後、出エッジを持たないノードからマスターノードへ向かってグラフをたどりながら、各ノードを実行可能な関数に変換する。つまり生成されるコードの構造は、元のブラウザ操作の順序をそのまま写したものではなく、依存関係の解決順に並べ替えられたものになる。この点は、生成コードを読むときに前提として理解しておく必要がある。

セットアップはPoetryとHAR取得の2段構え

導入手順はREADMEに明示されている。まず OPENAI_API_KEY を環境変数として設定し、poetry install で依存関係を入れ、poetry shell に入る。Jupyterから使う場合は poetry run ipython kernel install --user --name=integuru でカーネルを登録する。通信記録の取得は poetry run python create_har.py でブラウザを起動し、対象サービスにログインして目的の操作を一度実行する。このとき network_requests.har と cookies.json がローカルに書き出される。実行は poetry run integuru --prompt "download utility bills" --model gpt-4o のように行う。オプションには --har-path、--cookie-path、--max_steps（既定20）、--input_variables、--generate-code があり、--help で一覧を確認できる。モデルについては、グラフ生成には関数呼び出しをサポートする gpt-4o が推奨され、コード生成では o1-preview がアカウントで利用可能なら自動的に切り替わるという記述がある。

入力変数とコード生成の間にある未完成な継ぎ目

機能一覧の中で目を引くのは、入力変数が現時点ではグラフ生成でしかサポートされておらず、コード生成向けは準備中だとREADME自身が書いている点である。たとえば取得する年を切り替えたいといった要求は、グラフの段階では扱えても、出力されるPythonコードには反映されない可能性がある。--generate-code を付けて完全な統合コードを生成する機能は用意されているが、変数の外部化という観点ではv0は途上にある。同様に、認証の扱いも限定的である。2FAを使うサイトでも手順自体は変わらないと説明されているが、これは2FAを突破する仕組みがあるという意味ではなく、利用者自身が2FAを完了した後のCookieやセッショントークンを使うという意味である。トークンの有効期限が切れれば、HARとCookieを取り直す必要がある。

汎用のブラウザ自動化とは何が違うのか

比較対象として分かりやすいのはPlaywrightやSeleniumのようなブラウザ自動化である。これらはDOMのセレクタや画面操作を記述するため、対象サイトのHTML構造が変われば壊れるが、通信の詳細を知らなくても書ける。Integuru v0は逆で、HTTPリクエストの依存関係を解析するため、画面の見た目が変わっても通り抜けられる一方、内部エンドポイントのパラメータや認証方式が変われば生成コードはそのままでは動かない。またブラウザ自動化はヘッドレスブラウザを実行し続ける必要があるが、Integuru v0が生成するのはHTTPリクエストを行うPythonコードであり、実行時にブラウザを必要としない。どちらが優れているという話ではなく、対象サイトの変更が画面側で起きやすいのか、API側で起きやすいのかで選ぶべきものである。

ローカル保存とクラウドLLMの間で何が外に出るか

プライバシーに関する記述はREADMEのPrivacy Policy節にある。収集されたデータは network_requests.har と cookies.json としてローカルに保存される。ただしツールはOpenAIのGPT-4oとo1-previewというクラウドベースのLLMを利用しており、解析のためにHARの内容がAPIに送信されることを意味する。READMEには、このツールの利用によってLLMが訓練・改善されることはないと明記されている。とはいえ、Cookieやセッショントークンを含むファイルをそのまま扱う以上、対象アカウントの権限範囲と、送信内容が組織のポリシーに照らして許容されるかを事前に確認する必要がある。ローカル保存だから安全、という単純な話にはならない。

AGPL-3.0であることの実務的な意味

ライセンスはAGPL-3.0である。GPL系のライセンスの中でも、ネットワーク越しに利用者へ機能を提供する場合にソース公開の義務が及びうる点が特徴で、社内ツールとして閉じて使うのか、サービスとして外部に提供するのかで条件が変わる。生成されたコードがライセンスの対象になるかは、生成物が元のリクエスト構造をどの程度含むかという事実関係に依存し、ここで断定はできない。判断が必要な場合は法務に確認するべき論点である。なお、このリポジトリはv0であり、最新版は www.integuru.com で提供されているとREADMEは述べている。公開リポジトリの保守が今後どこまで続くかは、この記述からは読み取れない。

向く用途と、手を出さないほうがよい場面

定期的に同じ操作を繰り返す必要があり、対象サービスに公式APIがない、あるいはAPIでは目的を達成できない場合、Integuru v0は候補になる。HARを取得する手間と、生成コードを読んで保守する前提を受け入れられるなら、ゼロからリクエストを解析するより速い。逆に、認証トークンが短時間で失効するサービス、頻繁に内部APIの仕様が変わるサービス、複数人で長期的に運用する必要がある統合には向かない。生成コードは依存関係を解決する順に並んでおり、変更が起きたときにどこを直すべきかを判断するには、元のHARと突き合わせて読める力が要る。まずは小さな操作を1つ選び、--max_steps を小さく設定して生成されるグラフの粒度を確認するところから始めるのが現実的である。

編集部の結論

Integuru v0は、公式APIが存在しない、あるいは公開が遅いサービスに対して、自分のアカウントで行った操作を再現する小さなスクリプトを書きたい個人や少人数チームに向く。一方、認証情報の更新やエンドポイント変更を長期的に追い続ける必要がある大規模運用や、AGPL-3.0の条件を社内ポリシーで扱いにくい組織には向かない。導入を判断する前に、まずcreate_har.pyで取得したHARとcookies.jsonの中身を自分の目で確認し、生成されたコードがどのリクエストに依存しているかを読めるかどうかを試すべきである。READMEが示すとおり、入力変数はグラフ生成の段階までしか対応しておらず、コード生成側では未対応である点も、実際に使う機能がそこに含まれるなら判断材料になる。

公式情報源

1. Integuru-AI/Integuru on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README