QGIS向けAI Agent完全ガイド
AI Agentは
内のチャットパネルです。タスクを書くと、すでに開いているプロジェクトの中で、そのlayer、CRS、選択範囲、画面の表示範囲を使って動作します。私たちが開発しているツールなので、このガイドでは私たち自身のツールを説明します。
最初の実行、エージェントが扱える範囲、動作を決める2つのチップ、そして望まなかった実行をundoする方法について説明します。
1つのpromptでできること
同じパネルに、同じプロジェクト内で、次々と入力した4つの文章です。以下のものはすべて手作業で用意されたものではありません。
インストールとサインイン
QGISでPlugins -> Manage and Install Pluginsを開き、AI Agentを検索してInstallをクリックしてください。QGIS 3.28以降（QGIS 4を含む）、Windows、macOS、Linuxで動作します。
TerraLabツールバーからパネルを開き、Sign in / Sign upをクリックします。ブラウザが開くのでアカウントを作成すると、pluginが自動的に接続されます。APIキーもクレジットカードも不要で、最初は無料で実行できます。
最初の実行
手順ではなく結果を説明する
「建物を高さで色分けして」は、「プロパティを開き、graduatedレンダラーを選び、height fieldを選択して」よりも良いpromptです。エージェントは行動する前にプロジェクトを読み込むため、layer名やfield名、パスを指定するのはたいてい無駄な入力になります。
答えだけでなく、ステップを読む
メッセージの下にあるグレーの行が作業内容を示します：4 steps, 39.6s。展開すると、すべてのツール呼び出しが引数とその結果とともに表示されます。良い結果ともっともらしいだけの結果を見分ける方法はこれです。
尋ねられたら答える
実行は2〜4個の選択肢を持つ小さなカードで止まることがあります。私たちの例では2回尋ねられました：表示範囲には6,355のOSMフィーチャーがあり、3,124の建物のうち117だけがheightタグを持っていました。どちらも作業の実際の分岐点であり、後からtraceで確認できます。
何が変わったかを確認する
答えの下にあるチップが、実行によって作成または変更されたlayerを示します。1つをクリックすると、通常のQGISメニューが表示されます：Layersパネルに表示、ズーム、属性テーブルを開く、layer properties。
QGISでのステップ数に関わらず、1つのpromptは1回のrunです。実行は60回のツール呼び出しまたは40分で自動的に停止するため、うまくいかなくなったタスクが際限なく続くことはありません。
エージェントが扱える範囲
データ。 ローカルファイル、リモートファイル、WFS、WMS、XYZ、STACおよびCOG画像、OpenStreetMap抽出データ、ジオコーディング、ルーティング。GeoPackageをパネルにドロップすると、layerとして読み込まれます。
分析。 あらゆるProcessingアルゴリズム。パラメータ名や既知の落とし穴は推測ではなく調べた上で使われます。バッファ、結合、ゾーン統計、トポロジーチェック、OSM道路からの到達圏（isochrone）、線に沿った標高プロファイルなど。
カートグラフィー。 シンボロジー、categorizedおよびgraduatedレンダラー、ラベル、地図・凡例・スケールバー・方位記号を含む印刷レイアウト、そしてPDFまたはPNGへのエクスポート。
編集。 フィーチャーの追加、更新、削除、ジオメトリの修復、頂点編集、結合と分割。ロールバック可能な実際のQGIS編集セッション内で行われます。
質問への回答。 QGISの設定がどこにあるか、手作業でどう行うかを、公式QGISドキュメントへのリンク付きで答えます。無効なジオメトリの修正方法を尋ねると、runではなく答えが返ってきます。
AI EditまたはAI Segmentationがインストールされていれば、エージェントはそれらも操作します：promptから画像を変換したり、範囲内のオブジェクトのすべてのインスタンスをvectorizeしたりできます。
エージェント自身が成果を確認する
Medium以上のeffortでは、エージェントは地図をレンダリングし、自分が作った結果を確認します。レイアウトの実行ではまさにそれを行い、結果が読みにくいと判断して、完了する前に描画順序を修正しました。
この振る舞いは、良い意味でも注意すべき意味でも見ておく価値があります。3,124の建物のうち186だけが使える高さの値を持っていることを、nullだらけのfieldを黙ってスタイル設定するのではなく報告しました。一方で自信満々に間違うこともあるため、読むべきものはやはりtraceです。
コントロールを保つ
モデルとあなたのプロジェクトの間には、3つの仕組みがあります。
composerの+の隣にあるpermission chipが、いつ止まって尋ねるかを決めます。
| レベル | 確認するタイミング |
|---|---|
| Ask first | すべての変更の前 |
| Balanced（デフォルト） | 削除と上書きの前 |
| Autopilot | credit消費とPython実行を除き、確認しない |
Autopilotはセッション単位の選択です：QGISを再起動すると、前回何を選んでいてもBalancedに戻ります。どのレベルでも常に確認される2つのことがあります：credit消費を伴うものと、生のPythonの実行です。Pythonは実行前にコードを確認できます。
approval cardが、確認を求める際の見た目です。これから起きることを説明する一文と、あなたの答え。決定すると1行に折りたたまれるため、長い実行でも読みやすさが保たれます。
Undo。 すべての実行がcheckpointを残します。パネルヘッダーの矢印をクリックすると、新しい順に一覧が開き、プロジェクトが現在ある行にチェックが付いています。
行を選ぶと、プロジェクトはその状態に戻ります。restoreは戻る前の状態も記録するため、それ自体をundoすることもできます。Ctrl+Alt+Zは何も開かずに1つ戻ります。checkpointは個々のツール呼び出しではなく、runを単位としています。
適切なコンテキストを与える
エージェントはすでにプロジェクトを読み込んでいます：layer名、タイプ、CRS、フィーチャー数、field名、extent、キャンバス、選択範囲。あなたが追加するのは、エージェントが見ることのできないものです。
- 写真やデータファイル、またはこのプロジェクトのlayerを添付する。
- QGISのLayersパネルからlayerを直接パネルにドラッグする。
- ファイルをパネルのどこにでもドロップする：データはlayerとして読み込まれ、画像はモデルに送られる。
- メッセージ内で
@を入力し、データソースやインストール済みのQGIS pluginを指定する。
各プロジェクトは独自のチャットを保持します。ヘッダーの虫眼鏡アイコンで、タイトルとメッセージ本文から検索でき、チャットはMarkdownとしてエクスポートできます。
変更する価値のある2つの設定
Sendの前にあるEffortチップは、モデルを選ぶものではありません。どれだけの思考量を使うかを指定するものです。
| レベル | 内容 | プラン |
|---|---|---|
| Instant | できるだけ速く作業を開始する。計画やリサーチは行わない | Free |
| Medium | 計画を立て、結果を確認し、アルゴリズムやドキュメントを調べる | Pro |
| High | より深い計画立案、リサーチ、難しいタスクでの自律的な方向づけ | Pro |
Instantは「このプロジェクトのCRSは何か」や、単発のスタイル変更に適しています。Mediumは、このガイドのすべての実行（質問と自己確認を含む）を生成しました。Highは、他ならそのために午後の時間を丸ごと確保していたようなタスク向けです。
Settingsの最初のページにあるConnectorsが、データの取得元を決めます。39のソースのうち、デフォルトで10がオンになっています：OpenStreetMap、Overture、Natural Earth、NASA、Copernicus、Planetary Computer、各国の地図作成機関など。オンにする前に、それぞれが何を必要とするかが示されます。ほとんどは何も必要としません。
インストール済みのQGIS pluginも同じページに行として表示され、エージェントが名前で参照できるようになります。
Personalisationは、もう一つ訪れる価値のあるページです。AIがあなたを何と呼ぶべきか、あなたの仕事内容、あなたの業務についての説明、常時適用する指示、GISの経験、メートル法か尺貫法（インペリアル）か、新しいlayerの命名方法、そしてチャット間で保持されるメモ。
あなたのマシンから送信されるもの
すべてのメッセージは私たちのホスティングサービスに送信されます。送信される内容：あなたのリクエスト、プロジェクトの説明（CRS、extent、layerごとの名前・タイプ・ジオメトリタイプ・表示状態・フィーチャー数・field名・extent、加えてアクティブなlayerのサンプル行1件）、プロジェクトファイルのパス、直近のProcessing実行、最新のQGIS警告、そして添付したもの。
送信されない内容：raster・vectorファイルの中身、プロジェクトファイルそのもの、フィーチャーのジオメトリ、属性テーブル全体、そして尋ねていない他のプロジェクト。activation keyがツールの結果に現れることは一切なく、layer URI内のデータベースパスワードはすべての結果とtracebackから除去されます。
FreeとProの違い
Freeでは月10回のrun、高速モデル、すべてのツール、すべてのconnector、すべてのQGIS pluginを個人利用で使えます。Proは月250回のrunで49ユーロ：難しいタスクにはProモデル、MediumとHighのeffort、記憶と常時適用の指示、より長いrun、商用利用が可能です。
ツール呼び出し単位での課金はありません。60ステップのrunも3ステップのrunも同じコストです。
よくある質問
プロジェクトを壊すことはありますか？
変更することがまさに目的であり、その変更は取り消し可能です。Balancedは破壊的な操作の前に確認し、run checkpointは、承認すべきでなかったものを承認してしまった後でもプロジェクトを元に戻します。とはいえ、長いセッションの前にはプロジェクトを保存してください。まとまった編集の前にそうするのと同じです。
QGISにPythonを書き込みますか？
タスクに必要な場合、Pythonを実行することがあります。これはAutopilotを含むすべてのレベルで確認が入る唯一のことです。実行前にコードを確認できます。
間違っていた場合はどうなりますか？
言語モデルであるため、間違えることがあり、しかも自信満々に間違えることがあります。それがactivity blockの存在意義です：展開して、選んだ引数と返ってきた件数を確認してください。私たちの実行例では、3,124の建物のうち使える高さを持つのは186だけだと報告されました。地図を信頼する前に読む価値のある一行です。
runにはどれくらい時間がかかりますか？
質問なら数秒、実際の作業なら数分です。このガイドでは：ベースマップに43秒、建物と高さのグラデーションに6分30秒、レイアウトに2分37秒、各質問には1分未満。データ取得中もQGISは使用できます。
オフラインで動作しますか？
いいえ。ローカルモデルもオフラインモードもありません。pluginはあなたのマシン上で動作し、モデルは私たちの側で動作します。
私のデータはモデルの学習に使われますか？
いいえ。このサービスはQGISのステップを計画するだけで、それ以外のことはしません。
オープンソースですか？
pluginはGPL-2.0-or-laterの下でオープンソースです：ツールの実行部分、permissionモデル、ファイルとネットワークのガード、パネル。そのため、あなたのコンピュータ上で動くものはすべて監査可能です。ホスティングサービス、そのprompt、オープンデータのカタログはオープンソースではありません。
覚えておきたいこと
手順ではなく結果を説明してください。エージェントは先にプロジェクトを読み込むため、layer名やパスを指定するのはたいてい無駄な入力になります。
1つのpromptは1回のrunです。ステップ数に関わらず、60回のツール呼び出しまたは40分で自動的に停止します。
activity blockこそがこの製品です。展開することが、良い結果ともっともらしいだけの結果を見分ける方法です。
すべての実行がcheckpointを残し、restoreそれ自体もundoできます。後悔するような承認をしても、行き止まりにはなりません。
Effortが買うのは計画と確認であり、別の人格ではありません。Instantは即答し、Mediumは作業して検証し、Highは先に考えます。
Connectorsが、見つけられるデータを決めます。自国の地図作成機関をオンにすることは、どんなprompt文面よりも価値があります。
