AIエージェント自作のための基礎知識

世は大 AI 時代ということで、調べ事や開発に様々な AI を利用するようになりました。 AI 失業だの SaaS is dead だのと騒がしいですが、そういうのは今日は置いておきます。

AI を使うのも良いですけど、せっかくソフトウェアエンジニアをやっているのですから、自分で作ってみるのもいいですよね。 結論から先に書いておくと、AIエージェントも今どきは簡単に自作できるようになっています。

この記事では Google 製の Agent Development Kit (ADK) を使いますが、何を使うにせよ、そもそも AI エージェントがどう動いているか理解しておかないと効率が悪いです。 それだって AI に聞けば出てくる、、わけですが、まあ人間が要点をまとめた記事にもまだ五円くらいは価値があるかなってことでまとめてみました。 ... お察しの通り、AI に指示して書かせたわけですけど、まあ ymmt 監修ということで。

---

AI エージェント開発の基本概念と、Go で Google Agent Development Kit (ADK) を使ってエージェントを構築する方法を解説します。 LLM ベースのエージェント開発が初めての Go 開発者を対象としています。

目次

1. AI エージェントとは
2. エージェントとフロントエンドの通信
3. スレッド、ブランチ、セッション、ラン
4. フロントエンドの要件
5. ADK と genai SDK
6. Gemini モデル: Google AI Studio と Vertex AI
7. LLM エージェントの構造
8. インストラクション
9. グラウンディング
10. ツールの使い方
11. サブエージェント
12. 全体像

U-NEXTが良い

はじめにお断り。私は U-NEXT の株主で、優待で U-NEXT を利用しています。 この記事は銘柄を推奨するものではありません。投資は自己責任でお願いします。

我が家は夫婦揃ってインドア派で、インドアで楽しめる動画サブスクは重宝しています。 契約中のサービスは Amazon Prime Video, Netflix, Hulu。Disney+ は過去契約してました。 最近ここに U-NEXT が加わったのですが、比較して満足度が高いのでちょろっと紹介。

動画ビューワーの出来が良い

docker buildx bake で高速並列ビルド

Docker ビルド職人の朝は早いーー

毎日コンテナイメージを山ほどビルドしては捨てている皆様、おはようございます。 ビルドの速度はそのまま CI にかかる時間だったりするので、短縮には余念のないことと思います。

レイヤのキャッシュやマルチステージビルドといった基本テクニックについて、ご存じない方は以下の記事がお勧めです。

future-architect.github.io

この記事では、良い Dockerfile をさらに活用できる、かもしれない docker buildx bake について紹介します。

やんないほうがいいかも、GitHub Actions の setup-xxx での依存キャッシュ保存

GitHub Actions で CI している皆様、こんにちは。
GitHub Actions 便利ですよね。使わない日がないというくらい毎日お世話になっています。

さて、CI といえば良く問題になるのが実行時間。 長い待ち時間は開発効率を下げますし、プライベートリポジトリだと Runner の費用も嵩んでしまいます。 時間を短縮する方法は色々ありますが、一手目によく行われるのが依存パッケージのキャッシュじゃないかなと思います。

例えば Go で開発していると、依存パッケージは ~/go/pkg/mod にダウンロードして保存されます。 これを CI 実行のたびにダウンロードしてコンパイルするのは時間とお金の無駄というものです。

幸い、GitHub Actions には CI の実行間でこういった依存パッケージを保存して再利用できるキャッシュ機能があります。 詳しくは以下のドキュメントをご覧ください。

Caching dependencies to speed up workflows - GitHub Docs

とか書いてますが、面倒くさがりな私はこれまでまともにこのキャッシュ機能を調べたことはありませんでした。 なぜって GitHub はとても親切なので、以下のようにするだけでキャッシュ機能で依存関係を保存して再利用できるようにしてくれているからです。

jobs:
  test:
    name: Run tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-go@v5
      with:
        cache: true

注目は cache: true です。こうするだけで Go の依存パッケージをキャッシュしてくれます。 しかもデフォルトが true なので、実は書かなくても大丈夫。えらい！楽！以上！

・・・そうは問屋が卸さなかったのが今回の話です。

AlloyDB で初期ユーザーとさよならする話

AlloyDB, 正式には AlloyDB for PostgreSQL は名前が示す通り PostgreSQL 互換の Google Cloud 上で利用できるマネージドデータベースです。 AWS だと Aurora が類似のサービスで、ストレージとコンピュートのノードが分離したアーキテクチャになっていてスケーラビリティや可用性に優れます。

諸事情で最近 AlloyDB を使っているんですが、通常の PostgreSQL とはちょっと違う点があります。 たぶん最たるものがユーザーと role 周りでしょう。

PostgreSQL の通常のユーザー認証はユーザー名とパスワードで行われます。 AlloyDB のクラスタを作成するときも、postgres という初期ユーザーが平文で指定したパスワードで作られます。

他のマネージドサービスの認証は通常このようなユーザー名パスワード方式ではなく、IAM のユーザーないしサービスアカウントで行われます。 内部的には短期間で expire する認証トークンを発行して OAuth しているのでしょうが、クライアントライブラリ等が自動で処理するのが通常であるため、利用者観点では認証が自動で行われて快適かつセキュアです。 AlloyDB は通常のユーザーに加えて IAM ユーザーで認証して利用することもできます。

さて、そうなると当然平文パスワードで作成した初期ユーザーは捨てて IAM ユーザーだけにしたくなります。 結論から言えばできます。

メンテのいらないソフトウェア

ソフトウェアエンジニアとして働き始めて 20 年以上になります。 元々ソフトウェアでいろいろ作りたくて就いた職業なので、結構な数のプロダクトを開発してきました。

私がメインで開発したもので OSS として出ているものでは、

• [yrmcds]: memcached クローンで、レプリケーション機能などを持つ
• [usocksd]: SOCKS4/5 サーバー & ライブラリ
• [transocks]: アプリのネットワーク通信を透過的に SOCKS サーバーにプロキシする透過プロキシ
• [coil v2][coil]: Kubernetes の CNI ネットワークドライバ
• [moco]: MySQL を自動運用する Kubernetes オペレーター
• [accurate][]: Kubernetes 上で namespace ベースのソフトマルチテナンシーを実現するためのソフトウェア

などがあります。これらのソフトウェアの多くは、現役で使われています。

私の主な仕事はこれらのソフトウェアの開発・メンテナンスではありません。 過去の主要な仕事内容としては cybozu.com のローンチプロジェクトの責任者であったり、開発・運用の本部長であったり、今は新規プロダクトのアーキテクトを務めていたりします。

プロフェッショナルなソフトウェアエンジニアの心がけとして、以下のようなことが良く言われます。

コードを書くことが仕事じゃない。問題を解決できるなら、むしろコードは書かなくて済むほうがいい。

なぜなら、「コードを書くとバグがあったりメンテナンスの工数がついてまわったりする」からです。 そうだよなと思うと同時に、「いや俺、コード書きたくてソフトウェアエンジニアになったんですけど」と本音のところで思ったりしています。

で、本題。コード書きまくってソフトウェアプロダクト作りまくっても、そのバグやメンテナンスに時間を取られない方法はないのか。 あります。

OpenTelemetry 良い感じ

最初に断っておきますと、OpenTelemetry を良く知っていたり真面目に調査しようという人が読むべき内容はここにはありません。 公式ドキュメントなりをご参照ください。これは最近 OpenTelemetry を使いだした一般人の感想記事です。

さて、いけてる Web 開発者、特にバックエンド開発者の方はオブザーバビリティという言葉は聞き及んでいるかと思います。 なかでもオブザーバビリティ三種の神器と言われている（？）ログ、メトリクス、分散トレーシングをどう実装するか頭を悩ませているかもしれません。

頭を悩ませてきた、あるいは頭を悩ませている理由の一つは、これらを実装するときに特定の実装向けになりがちであったためです。 メトリクスであれば最近は Prometheus 向けに /metrics エンドポイントとして提供する実装が多いといった話です。しかしながら、 あらゆる人が Prometheus を使うわけでもないので、汎用的なソフトウェアを書く場合に悩ましかったりしたわけです。

OpenTelemetry は、逆説的に特定の実装を排して、SDK とプロトコルだけを規定することでどんなソフトウェアにも組み込んで良い、 一度組み込んだらメトリクスサーバーやトレーシングサーバーをいつでも変更可能になるよという CNCF のプロジェクトです。まだ 一部の機能、例えば Go SDK でログが未実装といったところはありますが、トレーシングやメトリクスは十分インストルメント可能です。

そんな噂を聞いて、新規のサービス開発でこれからやるなら OpenTelemetry でインストルメントしていくのかなと思いつらつらやってました。 以下、調べたり学んだりしたことと、現状できていることです。正確性は全然担保しないので、使うときはちゃんと調べてくださいね。