CLI tool for MapFan geospatial AI agent services. Query geocoding, POI search, and routing via natural language.
mapfan-agentは、MapFanの地理空間AIエージェントサービスを利用するためのCLIツールです。
CLI はトランスポートと認証を差し替え可能な薄いクライアントです。
- A2A モード（現行・本番想定）: AWS Bedrock AgentCore 上の MapFan A2A エージェントを、Cognito M2M 認証 + A2A
message/sendで呼び出します。応答は A2A Task として正規化して表示します。 - REST モード（ローカル開発フォールバック）: 旧
mapfan-agent-serverを REST +X-API-Keyで呼び出します。ローカル検証用に維持しています。
MAPFAN_TRANSPORT（a2a / rest）で切り替えます。
pip install mapfan-agent
# または開発時: uv sync --dev- Python 3.11+
- A2A モード: AgentCore の invoke エンドポイントと、Cognito M2M クライアント資格情報（
client_id/client_secret/ token endpoint / scope）。取得手順は A2A E2E ランブック を参照。 - REST モード: 稼働中の mapfan-agent API サーバー（URL と API キー）。
cp .env.example .env
# .env に COGNITO_CLIENT_SECRET と MAPFAN_A2A_ENDPOINT を設定
#（MAPFAN_TRANSPORT=a2a / MAPFAN_AUTH=cognito_m2m は .env.example の既定値）
mapfan-agent ask "東京駅の緯度経度を教えて"
mapfan-agent ask "東京駅の緯度経度を教えて" --json # 構造化出力
mapfan-agent repl # 対話モードMAPFAN_A2A_ENDPOINT（invoke URL）の求め方や secret 取得を含む手順は docs/demos/2026-07-09-a2a-e2e-runbook.md を参照してください。
export MAPFAN_TRANSPORT="rest"
export MAPFAN_API_URL="https://api.example.com"
export MAPFAN_API_KEY="your-api-key"
mapfan-agent ask "東京タワー周辺のカフェを探して"設定は デフォルト → TOML(~/.mapfan-agent/config.toml) → 環境変数 の順に上書きされます。secret（COGNITO_CLIENT_SECRET）は環境変数でのみ設定してください（TOML には書かない・コミットしない）。
| Variable | Default | Description |
|---|---|---|
MAPFAN_TRANSPORT |
rest |
トランスポート選択（a2a / rest） |
MAPFAN_A2A_ENDPOINT |
— | A2A invoke URL（?qualifier=DEFAULT 付き完全 URL） |
MAPFAN_AUTH |
none |
認証方式（none / cognito_m2m） |
COGNITO_TOKEN_ENDPOINT |
— | Cognito トークンエンドポイント |
COGNITO_CLIENT_ID |
— | Cognito M2M クライアント ID |
COGNITO_CLIENT_SECRET |
— | Cognito M2M クライアントシークレット（env のみ） |
COGNITO_SCOPE |
agents/mapfan.invoke |
要求スコープ |
MAPFAN_API_URL |
http://localhost:8000 |
REST モードの API サーバー URL |
MAPFAN_API_KEY |
— | REST モードの API キー |
[a2a]
transport = "a2a"
endpoint = "https://bedrock-agentcore.ap-northeast-1.amazonaws.com/runtimes/<...>/invocations?qualifier=DEFAULT"
[cognito]
auth = "cognito_m2m"
token_endpoint = "https://<domain>.auth.ap-northeast-1.amazoncognito.com/oauth2/token"
client_id = "xxxxxxxxxxxxxxxxxxxxxxxxxx"
scope = "agents/mapfan.invoke"
# client_secret は TOML に書かず COGNITO_CLIENT_SECRET 環境変数で指定
[api] # REST モード（ローカル開発フォールバック）
url = "http://localhost:8000"
key = "your-api-key"mapfan-agent ask "東京駅周辺のカフェを3件教えてください"
mapfan-agent ask "東京駅の緯度経度を教えて" --json # A2A Task を JSON で出力
mapfan-agent ask --api-url http://localhost:8000 "query" # REST の URL 上書きA2A モードでは応答を A2A Task として正規化し、テキスト（kind:text）とツール実行の封筒（kind:data）を表示します。--json で state / text / data / context_id を構造化出力します。
mapfan-agent repl会話コンテキスト（A2A の context_id）を保持し、前の回答を参照した追質問や、エージェントが追加入力を求める場合（input_required / HITL）の継続に対応します。
A2A クライアントは失敗を用途別の例外に分類します（mapfan_agent.client.errors）:
| 例外 | 意味 |
|---|---|
A2AAuthError |
認証失敗（401） |
A2AScopeError |
スコープ不足（403・契約上呼べない） |
A2AAgentError |
エージェント側エラー / 通信失敗 / Task failed |
A2ATimeoutError |
タイムアウト |
message/send は非idempotent（エージェントが書き込みを起こしうる）ため 5xx/ネットワークエラーでの自動リトライはしません。認証失敗（401）時のみトークンを 1 回強制更新して 1 回だけ再送します。
git clone https://github.com/geolonia/mapfan-agent.git
cd mapfan-agent
uv sync --dev
uv run pytest- A2A E2E ランブック — dev での実データ E2E 手順（secret 取得・invoke URL 導出・実行）
- Breaking changes / 設計判断 — v0.3.0 の破壊的変更と設計上の判断
This repository is mirrored between Geolonia and GeoTechnologies for joint development and hosting.
| Remote | URL | Purpose |
|---|---|---|
geolonia |
git@github.com:geolonia/mapfan-agent.git |
Geolonia-managed development |
geotech |
git@github.com:GeoTechnologies-Inc-DX/mapfan-agent.git |
GeoTechnologies hosting and handoff |
Push shared updates to both remotes when needed:
git push geolonia main
git push geotech mainMIT