【自由研究】地理分析AIエージェントのトークン消費を削減するSkills改善の検証

こんにちは。
今回は、AIエージェントによる地理分析タスク実行時のトークン消費数削減についてまとめます。

地理分析を手助けするSkillsを色々改良したうえで、Antigravity CLIのトークン数を削減できないかを、探求しています。
特に地理分析のような幾何計算を伴うタスクでは、トークン数が増大されうるため、手立てが必要となります。

実験では、Skillsの改善を「初期版」「改善1」「改善2」と段階的に進め、トークン消費量がどう変化したかを検証してみました。

初手に結論

商圏分析およびポリゴン分析をSkillsを介して行ったところ、Skills「改善2」案が最もトークン数削減となりました。

また、「どれだけAIエージェント内で思考回数を減らし、AI APIへの問い合わせ回数を削減するか」がトークン数削減に直結しそうでした。
AIエージェントが一度の問に対して何度も思考を繰り返していくうちに、インプットトークンが増大→AI APIへの問い合わせ回数増大という負の連鎖となると考えられます。

これの対策として、「改善2」では問い合わせを減らすように、なるべく一回（ワンショット）で問い合わせるように命令を行っています。

実験内容

実験に使用したAIエージェントの環境の説明から、実験内容、結果までを記載します。

今回のAIエージェントの環境の構成

Skillsを介して、geospatial_preculc.pyという地理計算ファイルを呼び出す仕組みとなります。
また、実験ではAIエージェントへ提供するSkillsの仕様を段階的に見直し、最適化を図りました。

experiment-img

ちなみに、Skillsは、<pj>/.agents/skills/<skill名>/SKILL.mdとして配置しています。

また、Skillsの各バージョン（初期版 → 改善版1 → 改善版2）の特徴は以下の通りです。

初期版
初期版ではSkillsを用意したものの、AIエージェントが処理に必要な仕様を確認しようとして、view_fileや find_by_nameなどのファイル探索コマンド（Antigravity CLI内で使用される思考名称）を多用していました。
その結果、ファイル探索を行うなど、本来の計算に入る前のステップ数が無駄に増加し、かえってトークン消費を悪化させる要因となっていました。　
初期版 → 改善1
初期版を見直し、無駄なファイル探索を徹底的に排除しました。
- ファイル閲覧の完全排除:
  view_file や find_by_name の使用を明示的に禁止。
- 関数チートシートの埋め込み:
  スキル本文内に round_coords, haversine_distance等々Pythonファイル内の関数名と引数仕様を直接記載。
改善1 → 改善2
改善2では、実行ルールの厳格化を行いました。
- 「1ショット連結実行」ルール:
  なるべく、「座標丸め込み等の幾何計算を1つのコマンドで完結させること」「別のスクリプトがある場合に、&&で連結して1回のrun_command で同時実行すること」を義務付けました。

検証方法

検証では、Q1（10問）とQ2（10問）の計20問の地理計算問題を解き、その際の消費トークン数を求めました。
「初期版」「改善1」「改善2」ごとに同じ20問を解き、平均トークン数を算出します。
Skills有り無しで対照実験を行い、どれだけトークン数が削減できているかを判断します。

※ キャッシュやトークン数が偏ることを防ぐため、1問ごとにサブエージェントを呼び出し、真っ白な状態から問を投げています。

Q1: 商圏分析
問

    基準地点（35.681236, 139.767125）から、半径2.0kmの円形バッファを構築し、
    対象地点（35.684123, 139.752512）がそのバッファの内部に含まれるかを判定してください。

答え

    基準地点（35.681236, 139.767125）から対象地点（35.684123, 139.752512）までの
    測地線距離は約 **1.36 km (約1,361 m)** です。 
    - 距離が2.0 km（2,000 m）未満であるため、対象地点は円形バッファの **内部に含まれます
    （判定: 含まれる）**。  
    - 基準地点（東京駅周辺）と対象地点（皇居周辺）は
    直線距離で約1.36km離...

Q2: ポリゴン分析
問

    以下の座標点 (35.689655, 139.751848), (35.689591, 139.759252), 
    (35.681244, 139.761112), (35.679608, 139.750591), (35.689655, 139.751848) 
    で形成されるポリゴンの『総面積』および『重心』を算出してください。

答

    指定された座標点により形成されるポリゴンの計算結果は以下の通りです。  
    - **総面積**:   
    - 測地線面積 (WGS84楕円体面): **約 830,255.62 ㎡**（約 0.8303 ㎢ / 約 83.03 ha）   
    - 平面直角座標系（第IX系）投影面積: **約 830,090.58 ㎡** 
    - **重心（緯度, 経度）**:   
    - **(35.684744, 139.7555...

検証結果 - Q1,2で使用したトークン数

各世代において、地理分析タスク（Q1、Q2）をSkillsの有無（Skills_N: 無、Skills_Y: 有）で実行した際の測定結果を整理しました。

初期版はSkillsを参照していない場合と比較し、むしろ悪化している結果となりました。
改善1はトントン、改善2では大きくトークン数の削減が見られました。

Skills	Q1: Skills_N (無)	Q1: Skills_Y (有)	Q1 削減効果	Q2: Skills_N (無)	Q2: Skills_Y (有)	Q2 削減効果
初期版	37,961.0 ± 13,483.1	36,930.7 ± 10,949.5	-2.7% (拮抗)	30,456.3 ± 3,728.0	36,942.9 ± 6,698.5	+21.3% (悪化)
改善1	46,761.5 ± 9,281.1	38,225.2 ± 4,531.3	-18.3% (改善)	40,313.8 ± 5,789.0	41,555.2 ± 6,574.9	+3.1% (拮抗)
改善2	45,153.9 ± 8,341.8	23,848.2 ± 3,968.6	-47.2% (半減)	40,460.2 ± 3,311.1	23,353.3 ± 1,634.1	-42.3% (半減)

考察材料 - 実行ステップ数（API呼び出し回数）の変化

また、1問の中でAIエージェントが何回思考し、AI APIを呼び出しているかを調査しました。
こちらもトークン数の傾向と同様に、初期版は悪化しました。
改善1はトントン、改善2は良化となりました。

Skills	Q1: Skills_N (無)	Q1: Skills_Y (有)	ステップ数変化	Q2: Skills_N (無)	Q2: Skills_Y (有)	ステップ数変化
初期版	6.70	9.00	+34.3% (増加)	6.20	9.20	+48.3% (増加)
改善1	6.40	6.20	-3.1% (拮抗)	6.00	6.20	-3.3% (拮抗)
改善2	6.40	4.00	-37.5% (短縮)	6.00	4.00	-33.3% (短縮)

考察

改善1では探索を禁止したことでステップ数自体はSkills無と同等まで抑えられました。
Q1では-18.3%の改善が見られたものの、Skills経由の呼び出し回数が依然として多く、Q2では+3.1%とトークン消費が拮抗してしまいました。

一方、「ワンショット連結実行」をルール化した改善2では、Q1,2ともにAPI呼び出し数が大きく縮小しました。
これはAIエージェント内の思考の中でAI APIを別途呼び出した回数が減少したためであると考えられます。

思考内でAI APIの呼び出し回数を減らしたことで、対話履歴の累積によるインプットトークンの肥大化を強力に抑え込み、トークン消費量を約半分（Q1: -47.2%、Q2: -42.3%）まで下げることに成功しました。

参考 - Skills

ご参考までに、今回使用したSkillsテキストを張っ貼っておきます。

初期版

    ---
    name: geospatial_optimization
    description: 地理空間データ処理におけるオフライン幾何演算および座標丸め込み（正規化）のルールを適用するスキル。
    ---

    # 空間認知AIエージェント向け地理空間データ＆ツール呼び出し最適化ガイドライン（Geospatial SKILLS）

    ## オフライン幾何演算および座標正規化の徹底ルール
    地理空間情報に関する問い合わせを処理する際、以下の「完全オフラインローカル処理」および「座標丸め込みルール」を一切の例外なく適用してください。

    1. 座標値の小数点以下第5位への即時丸め込み（オフライン処理）
    - ユーザーから受け取ったすべての位置座標、あるいは外部から取得したPOI情報は、処理を始める前に必ず「小数点以下第5位（数メートル単位の精度）」へとオフライン（PythonやJS）で数値を丸め込んでください。
    - 生の精緻すぎる座標（小数点以下6〜12桁など）をそのままツールパラメータやプロンプト内に流してはいけません。

    2. オンラインAPIの制限とオフライン幾何計算の実施
    - 以下の基本幾何計算では外部APIを呼び出さず、完全オフラインで完結するPythonコードを用いて実行してください。
    - 距離計算：Haversine公式を用いた2点間の直線大圏距離の算出。
    - 方位計算：2点間の角度（0〜360度）および8方位（北、北東など）の算出。
    - 面積計算：ポリゴン図形の総面積算出。
    - 円形バッファ生成：指定した半径に基づく円形境界ポリゴンの動的生成。
    - 包含判定（ジオフェンス）：ある座標点がポリゴンの内側か外側かの判定（Point-in-Polygon）。
    - オフラインでのPython計算を行う際は、処理を実装する前に必ず `geospatial_preculc.py` をツール（view_file等）で閲覧してください。そのファイル内に用意された幾何計算関数がタスクに必要かつ適しているかを確認し、適している場合はそれをインポートして使用してください。

改善1

---
name: geospatial_optimization
description: 地理空間データ処理におけるオフライン幾何演算および座標丸め込み（正規化）のルールを適用するスキル。
---

# 空間認知AIエージェント向け地理空間データ＆ツール呼び出し最適化ガイドライン（Geospatial SKILLS）

## オフライン幾何演算および座標正規化の徹底ルール
地理空間情報に関する問い合わせを処理する際、以下の「完全オフラインローカル処理」および「座標丸め込みルール」を一切の例外なく適用してください。

1. 座標値の小数点以下第5位への即時丸め込み（オフライン処理）
- ユーザーから受け取ったすべての位置座標、あるいは外部から取得したPOI情報は、処理を始める前に必ず「小数点以下第5位（数メートル単位の精度）」へとオフラインで数値を丸め込んでください。
- 生の精緻すぎる座標（小数点以下6〜12桁など）をそのまま外部ツールパラメータやプロンプト内に流してはいけません。

2. オンラインAPIの制限とオフライン幾何計算モジュールの直接利用
- 以下の基本幾何計算では外部APIを呼び出さず、必ず完全オフラインで完結するPythonコードを用いて実行してください。
  - 距離計算：Haversine公式を用いた2点間の直線大圏距離の算出。
  - 方位計算：2点間の角度（0〜360度）および8方位の算出。
  - 面積計算：ポリゴン図形の総面積算出。
  - 円形バッファ包含判定：中心点からの直線距離を算出し、バッファ半径以下か判定。
  - 包含判定（ジオフェンス）：ある座標点がポリゴンの内側か外側かの判定。
- **【重要】ファイル閲覧（view_fileやfind_by_name等）は不要です。** 事前に以下の幾何計算モジュールが用意されているため、ファイルを閲覧・検索することなく直接インポートして使用してください。
  - モジュールパス: `~/<pj>/geospatial_preculc.py`
  - 使用例:
    ```python
    import sys
    sys.path.append("~/<pj>")
    from geospatial_preculc import round_coords, haversine_distance, point_in_polygon, calculate_polygon_area, calculate_polygon_centroid
    ```
  - 主要関数仕様:
    - `round_coords(lat, lon, precision=5)`: 座標を丸め込み
    - `haversine_distance(lat1, lon1, lat2, lon2)`: 楕円体上の距離（メートル単位）を返却
    - `calculate_polygon_area(polygon_coords)`: WGS84楕円体上の総面積（平方メートル単位）を返却
    - `calculate_polygon_centroid(polygon_coords)`: 重心 `(緯度, 経度)` を返却
    - `point_in_polygon(lat, lon, polygon_coords)`: 点がポリゴンに含まれるか判定（bool）

改善2

---
name: geospatial_optimization
description: 地理空間データ処理におけるオフライン幾何演算および座標正規化の汎用ルールを適用するスキル。
---

# 地理空間データ処理最適化ガイドライン（Geospatial SKILLS）

## 目的
地理空間データを扱う際のAPI呼び出しコストおよびトークン消費を最小化するため、以下のオフライン幾何演算・座標正規化ルールを適用してください。

## 1. 座標正規化とオフライン幾何計算の原則
- **即時正規化**: 取得・指定された座標（緯度経度）は、処理開始時に必ず小数点以下第5位に丸め込んでください。
- **オフライン完結**: 距離、面積、重心、バッファ判定、内外判定、方位角などの基本幾何演算では外部APIを呼び出さず、用意されたオフライン幾何計算モジュールを活用してください。
- **ファイル閲覧の省略**: モジュール探索や閲覧（view_file, find_by_name等）は行わず、以下のモジュール仕様を参照して直接インポートしてください。

## 2. 幾何計算モジュール仕様
モジュールパス: `~/<pj>/geospatial_preculc.py`

````python
import sys; sys.path.append("~/<pj>")
import geospatial_preculc as gp
````

### 提供関数一覧（自動丸め込み・WGS84楕円体準拠）
1. **多角形要約（総面積・重心一括）**:
   `gp.calculate_polygon_summary(coords)` -> 総面積（m²）と重心 `(lat, lon)` を一括取得
2. **円形バッファ包含判定**:
   `gp.check_buffer_containment(center_lat, center_lon, radius_km, target_lat, target_lon)` -> 包含判定（bool）と2点間距離（m）を一括取得
3. **2地点間大圏距離**:
   `gp.haversine_distance(lat1, lon1, lat2, lon2)` -> 楕円体上の距離（m）
4. **2地点間方位角**:
   `gp.calculate_bearing(lat1, lon1, lat2, lon2)` -> 方位角（0〜360度）と8方位文字列
5. **多角形総面積**:
   `gp.calculate_polygon_area(coords)` -> WGS84楕円体上の総面積（m²）
6. **多角形重心**:
   `gp.calculate_polygon_centroid(coords)` -> 重心座標 `(lat, lon)`
7. **点の内外判定（ジオフェンス）**:
   `gp.point_in_polygon(lat, lon, coords)` -> 包含判定（bool）
8. **座標丸め込み**:
   `gp.round_coords(lat, lon, precision=5)` -> 丸め込み後座標 `(lat, lon)`

## 3. コマンド実行効率化ルール（ワンショット実行の原則）
- **1コマンド完結**: 座標丸め込みと幾何演算を別々に実行せず、モジュール関数を用いて1回の実行で完結させてください。
- **他スクリプトとの連結実行**: 幾何計算コマンドの末尾に `&& ~/<pj>/another-files.py` を連結し、必ず1回の `run_command` 内で同時実行してください（複数ターンのツール呼び出し厳禁）。
  - コマンド例:
    ````bash
    python3 -c 'import sys; sys.path.append("~/<pj>"); import geospatial_preculc as gp; print(...)' && python3 ~/<pj>/another-files.py
    ````

## 4. 回答出力ルール
- 丸め込み後の全座標の再掲や計算途中式の長文出力は避け、計算結果の数値や判定結果のみを簡潔に回答してください。推測や提案は含めないでください。

おわりに

AIエージェントのぐるぐる思考によるインプットトークン増大には気を付けようねというお話でした。
噂には聞いていたことですが、定量的に観測すると、気を付けようとなります。

以上、自由研究でした！

それでは。