例外にならない失敗を型で閉じる — Gemini API のレスポンスを判別可能ユニオンに正規化する
HTTP 200 なのに本文が空、という失敗は try/catch では捕まりません。finishReason と blockReason を判別可能ユニオンに正規化し、never による網羅性チェックで処理漏れをコンパイル時に潰す設計をまとめました。
Managed Agents が静かに止まった朝、ログに手がかりが何も残っていなかった — 走行を外側から追える観測層の設計
Gemini Managed Agents はサンドボックスが Google 側にあるため、止まったときに自分のログ基盤へ手がかりが残りません。ストリームイベントを刻んで台帳化し、無音の停止を検知し、後から読める事後ログに畳む観測層を、そのまま動く TypeScript で設計します。
Gemini API × TypeScript 型安全AIアプリケーション設計ガイド — Zodスキーマ・Structured Output・ストリーミングの統合アーキテクチャ
Gemini APIとTypeScriptで型安全なAIアプリケーションを構築する方法を解説。Zodバリデーション、Structured Output、ストリーミング、エラーハンドリングを統合した本番アーキテクチャを実装します。
Gemini API × tRPC v11 × Prisma でつくる型安全 AI バックエンド — リアルタイムストリーミングからミドルウェア認証・本番運用まで
tRPC v11 の subscription で Gemini API ストリーミングをリアルタイム配信し、Prisma で型安全に会話を永続化する本番設計を解説します。ミドルウェア認証・レート制限・落とし穴対策まで実コード付きでまとめました。
Gemini API の本文が途中で切れる — finish_reason: MAX_TOKENS を検知して続きを継ぎ直す実装メモ
長文生成で末尾が文の途中でぷつりと切れる。原因の多くは finish_reason: MAX_TOKENS です。例外も 200 のまま静かに混入するこの事故を検知し、続きを継ぎ足して全文を取り戻す実装を、思考トークンの落とし穴とあわせてまとめました。
Gemini の画像生成 preview モデルが 6月25日に停止します — GA 版への移行で確認したコード差分と検証手順
6月25日に停止する gemini-3.1-flash-image-preview / gemini-3-pro-image-preview から GA 版へ移行した作業記録です。モデルIDの確認手順、Python のコード差分、停止前にしかできない回帰チェック、切り替え順序まで実例で整理しました。
Gemini API の空応答を finish_reason から逆引きする — 診断フロー・再試行分類・監視の実務
response.text が空になる問題は candidates・prompt_feedback・finish_reason の3層で診断できます。思考トークンによる出力枯渇の検出、再試行可否の分類器、空応答率の監視まで、本番で運用している実装をまとめました。
Gemini 3.2 API 実装ガイド — 正しいモデルID・3.1 からの移行と本番チェックポイント
Gemini 3.2 を API から呼び出すための正しいモデルID、Gemini 3.1 からの移行時の変更点、Python・TypeScript の実装例、本番環境への移行チェックリストをまとめました。
Gemini API のローカル開発を msw と HTTP フィクスチャで再生する — 6 サイト並行で API クォータを圧縮した記録/再生パターン
Gemini API を呼ぶ UI を毎回本物の API で確認していると、1 日に数百回の重複呼び出しが発生します。msw でフィクスチャを再生する仕組みを 6 サイトに導入したら、月の Gemini API 課金が想像以上に静かになりました。記録/再生の実装と運用ポリシーをまとめています。
Gemini Live API で画面共有しながら音声で対話する『AI ペアプログラマー』を TypeScript で構築する
Gemini Live API と getDisplayMedia で『画面を見せながら音声で相談できる AI ペア』を TypeScript で構築する手順を、コスト最適化と落とし穴まで含めて実装プレイブックにまとめました。
Gemini API × Drizzle ORM で型安全な AI チャットストアを構築する — マルチターン保存・スレッド分岐・ベクトル検索の本番設計
Gemini API のマルチターン会話を Drizzle ORM で型安全に保存・検索する本番設計を解説します。ストリーミング保存、スレッド分岐、Function Calling 履歴、pgvector 連携、マイグレーション戦略まで、実装で詰まりやすい論点を実コード付きでまとめました。
Zod × Gemini API: TypeScript で構造化出力を型安全に扱う実装パターン
Gemini API の構造化出力を Zod スキーマで検証する実装パターンを解説します。as による型キャストの落とし穴、JSON Schema への変換、検証失敗時のリトライ設計までコード付きで紹介します。