こんにちは！
突然ですが、私は将棋が大好きです！

ということで、今回は Agent Development Kit（ADK）を活用して、将棋対局データ分析エージェントを作ってみました！！

私の実戦棋譜データ（今回は将棋ウォーズの棋譜を使用）をチャット窓にポイッと投げるだけで、自動でファイル化して DB に反映、さらには自然言語で自分の戦績等を分析してくれるスゴい奴です。

このブログでは、私が辿った完成までの道のりを時系列順でそのまま紹介できればと思います！

今回の開発環境

  • OS : macOS (Darwin)
  • Python : 3.12.13（pyenv 2.8.1 / venv）
  • エージェント環境 : google-adk 2.7.1
  • LLMモデル : gemini-3.1-flash-lite（Vertex AI経由）
  • DB : SQLite（shogi.db：分析用に games / moves の2テーブル）

1. エージェントの土台作り

機能面を開発していく前に、エージェントの基本構造となる雛形（プロジェクト）を作成していきます。

仮想環境が起動している状態で ADK をインストールし、
pip3 install --upgrade pip
pip3 install "google-adk>=2.3.0"

必要なディレクトリを作成・移動します。
mkdir ./agents
cd ./agents

そこで adk create my_agent を実行すると…
これだけでagent.py や __init__.py などの必要なファイルが一瞬で自動生成されます！！！
※__pycache__と.adkは後から作っています。

エージェントを作るにあたり、「そもそもどんなフォルダ構成にすればいい？」「どのファイルから書き始める？」と迷ってしまいそうなものですが、コマンド一発で動く土台が手に入るのは助かりますね。おかげで「これならエージェントを完成させられるかも！」という気持ちが湧いてきました！！

初学者の躓きポイントをぶっ飛ばして、いきなり開発をスタートできる ADK の便利さに脱帽です。

ADK、最強すぎる！！！

2. 棋譜テキストを自動ファイル保存

ここからは機能の開発に入っていきます。

まずは、将棋ウォーズの対局履歴からコピーしてきた棋譜テキストをチャット窓に貼り付けたら、そのまま保存してくれる仕組みを作ります。

2.1. 保存先フォルダの準備

まず、生の棋譜データを蓄積するためのフォルダdata/kifu/を作成します。

2.2. save_kifu ツールを作成

次に、save_kifu ツールを作成します。

  • チャット窓に送信された棋譜テキストから「開始日時・先手・後手」を読み取る。
  • YYYYMMDD_先手名_vs_後手名.kif という命名規則で data/kifu/ に保存。
  • 同名ファイルがあれば自動で連番を振る。


これで1局分の棋譜テキストを投げると、綺麗に整理されたファイルとして保存できるようになりました！

2.3. 複数の棋譜データの一括送信にも対応

1局ずつ送るのも面倒なので、複数の対局データが連続で繋がったテキストが来ても一括処理できるように改良しました！

  • _split_records で「開始日時」を区切りに複数棋譜へ分割。
  • 1回のメッセージで一括保存できるように save_kifu ツールを拡張。


これで複数の棋譜データも一気に取り込める体制が整い、利便性が向上しました！

3. DB への自動反映＆同期提案

次に、保存した .kif ファイルから対局情報を読み取り、DB に自動で反映させる仕組みを構築していきます。

3.1. データベース（SQLite）の作成とテーブル設計

まずは対局データを蓄積するための SQLite データベース（shogi.db）を用意し、分析に必要な2つのテーブルを設計・定義しました。

  • games テーブル: 対局の全体情報（対局日、先手名、後手名、勝者など）を管理。
  • moves テーブル: 1手ごとの指し手（表記）と消費時間を管理。

3.2. db.py と kifu_parser.py の作成

DB操作をモジュール化して綺麗に管理するため、新たに db.py を作成しました。

  • kifu_parser.py : KIF形式のテキストから勝敗や指し手情報をパースして構造化データに変換するモジュール。
  • db.py : SQLiteへの接続管理を行うモジュール。メインとなる update_kifu_db() 関数は、data/kifu/ 内にある未登録の .kif ファイルを読み込み、パースされた対局データを games および moves テーブルへ安全に追加登録する役割を担う。

処理を役割ごとにスクリプト化しておくことで、手動で何度も取り込み処理を行ってもデータが重複しないクリーンな設計になりました！

3.3. agent.py へのツール組み込みと動的呼び出し

作成した db.py 内の更新ロジックを agent.py にツールとして連携し、エージェントが会話の流れで自発的に実行できるように Instruction を調整します。

  • エージェントに update_kifu_db ツールを付与。
  • 「DBを更新して」という直接的な表現だけでなく、「この棋譜もDBに取り込んでおいて〜」といった砕けた表現でも、文脈を理解してツールを実行。

ファイル保存時に、エージェント側から「最新のDBに同期しますか？」と提案してくれることもあり、一気に “AIエージェントっぽさ” が出てテンションが上がりました！！

4. 安全な SQL 検索

ここで1つ問題が発生します。

「直近10試合の私の対局結果は？」と聞くと、一見それっぽい回答が返ってくるのですが、データが全くのデタラメでした。

めっちゃ負け越してるやん！！！！（実際は半分くらい勝ってます…）

しかし、適切なレスポンスが帰ってこないのも当然で、当時のエージェントは「保存」と「DB反映」のツールしか持っておらず、DB の中身を読み取る手段が無かったのです。

4.1. query_kifu_db ツールの追加

解決策として、エージェントが自発的に SQL を投げて DB を検索できるように query_kifu_db を作成しました。

ただ、AI に SQL を放任するのはちょっと不安。

そこで、以下のような安全対策を施しました！

  • SELECT以外の文を正規表現でブロック（INSERT や DROP などは即却下）。
  • DB 接続を mode=ro（読み取り専用）で開く。
  • 取得結果は最大200行に制限。


これで、統計や履歴系の質問を投げたときは、必ず query_kifu_db で実際のデータを取得してから回答するようになりました！

しかし、この回答を見てもう一つの問題に気づきます。
エージェントに「私 ＝ abcdef1234（仮ユーザー名）」であることをまだ教えていませんでした…

5. 『私』を認識させる

ということで、Instruction に以下を追記して解決します！

  • 「ユーザー本人 ＝ abcdef1234」という前提を追加。
  • 先手の場合も後手の場合もあるため、勝敗判定時は DB の sente_player と gote_player の両方を見て判断させる。


これで、DBを読み取って、私が先手・後手双方で残した戦績を提示してくれるエージェントの誕生です！！

主機能まとめ

内容が想定よりも長くなってしまいましたが、今回構築した将棋対局データ分析エージェントの主な機能は以下の3点です！

  • 棋譜の自動保存・ファイル化機能 (save_kifu)
    チャット窓に送信された棋譜テキストから対局情報を読み取り、.kif ファイルとして整理・保存。一括保存にも対応。
  • DBへの自動反映＆同期提案 (update_kifu_db)
    保存された棋譜をパースし、SQLite (shogi.db) へ未登録データのみを安全に追加。「新しい棋譜取り込んで」といった口語での指示や、エージェント側からの同期提案も可能。
  • 安全な SQL 検索によるリアルタイム戦績分析 (query_kifu_db)
    自然言語からユーザー本人の勝率や対局傾向を安全かつ正確に集計・回答。

今後の展望

今回は安全性を考慮して将棋ソフトのインストールは行なっていませんが、本当は以下のような機能も搭載して、正真正銘の “分析” エージェントを作りたかったです！

  • 将棋ソフトや外部APIと連携し、評価値や戦型（居飛車、四間飛車など）の深掘り分析
  • 傾向・強み・弱み等の分析と具体的な対策立案

他にも、以下のような機能を入れればもっと便利になるなと、ブログを書きながら感じていました。

  • 他のアプリ（将棋クエストなど）の棋譜データや形式にも柔軟に対応
  • ユーザー名の秘匿化処理（ブログやSNS共有用）

おわりに

ADK を使うと、ツールの追加やプロンプトの調整だけで “AIのできること” がどんどん増えていくので、開発していてめちゃくちゃ楽しかったです！

一方で、ブログを書いてアウトプットしたことで見えてきた改善点もありました。
まだまだやりようがあるので、いつか改良版を作ってみたいものです。

今回はここまでになります。
最後までお読みいただき、ありがとうございました！🙇‍♂️