OpenAI Agents SDKとGoogle ADKでAgent開発を始めるメモ（Mac/Windows）

はじめに

最近、AI Agentまわりの情報を追っていると、OpenAI AgentKit、OpenAI Agents SDK、Google ADK、Agent Platformなど、似たような名前が一気に出てきて少し混乱しました。

自分の理解では、OpenAI側はAgentKitという大きな枠組みがあり、コードを書いてAgentを作るならOpenAI Agents SDKから入るのが分かりやすいです。一方、Google CloudやGeminiを中心に考えるなら、Google Agent Development Kit、つまりADKが入り口になります。

※本記事は2026年5月31日時点の公式ドキュメントを見ながら整理しています。Agent関連ツールは更新がかなり速いので、実際に触るときは公式ドキュメントも確認しておきます。

この記事では、まずAgent開発の基礎用語をざっくり整理し、そのあとMacとWindowsの両方でOpenAI Agents SDKとGoogle ADKを動かすところまで試します。主軸はローカル開発ですが、最後にCloud Run、Agent Runtime on Agent Platform、GKEなど、デプロイするときの選択肢もメモしておきます。

この記事は、Agent開発シリーズのPart 1として書いています。次回以降は、SREやインフラエンジニアの業務を題材に、Runbook調査Agent、証明書更新チェックAgent、Kubernetes障害調査Agentのような小さいAgentを作ってみる予定です。

Agent開発が気になっている理由

Agentは、単にAIに質問するだけの仕組みではないと捉えています。

ざっくり捉えるなら、Agentは「モデルに考えさせ、必要に応じてツールを使わせ、結果を確認しながらタスクを進めるアプリケーション」くらいの理解がしっくりきました。

これが注目されている理由は、開発や運用の現場にある繰り返し作業と相性が良いからだと思っています。

ログを見て、よくある障害パターンに当てはめる
Runbookを探して、手順を要約する
Kubernetesの状態を確認して、怪しいPodやEventを洗い出す
証明書の期限やWAF/CDN/FWの設定変更を確認する
GitHub IssueやPull Requestから作業計画を作る

これらは、毎回ゼロから考えるというより、情報を集めて、判断して、決まった形で報告する作業です。こういう作業にはAgentが入りやすいと感じています。

もちろん、何でもAgentにすればよいわけではありません。最初は「読取り中心」「失敗しても影響が小さい」「結果を人間が確認できる」タスクから始めるのが現実的だと感じました。

Agentを構成する部品

公式ドキュメントやいくつかのサンプルを見ていると、Agentアプリケーションはだいたい次の部品で考えると整理しやすいと感じました。

部品	役割
Model	文章理解、推論、ツール選択を行う中核
Instructions	Agentの役割、制約、出力形式を決める
Tools	API、CLI、DB、ファイル操作など外部世界に触る口
Agent loop	モデルの判断、ツール実行、結果確認を回す処理
Memory / Context	会話履歴、設定、ドキュメント、検索結果など
Guardrails	禁止操作、承認フロー、入力/出力チェック
Observability / Evals	実行履歴、失敗理由、品質評価、回帰テスト

最初に作るなら、構成はもっと小さくて大丈夫です。

自分なら、まずは「1つのAgent」「1つのTool」「1つの入力」「1つの出力形式」くらいから始めます。その方が、何が起きているか追いやすいです。

どのツールから触るか

今回は、入り口としてこの2つを見ます。

選択肢	向いているケース
OpenAI Agents SDK	OSS寄り、コードファースト、OpenAIモデルでAgentを作りたい
Google ADK	GeminiやGoogle Cloud連携を見据えてAgentを作りたい

OpenAIのAgentKitは、Agent Builder、Connector Registry、ChatKit、Evalsなどを含むAgent開発・運用のための製品群です。ローカルでコードを書いてAgentを作るなら、まずOpenAI Agents SDKから触ると理解しやすいと感じました。

Google ADKは、Agentをコードで定義し、ローカルで実行・確認し、将来的にGoogle CloudやAgent Platform方面へ広げやすい開発キット、という理解です。

前提条件

手元では、次のような環境を想定して進めます。

項目	推奨
OS	macOS または Windows 10/11
Python	3.10以上（3.11以上を推奨）
Node.js	LTS版
エディタ	VS Code
ターミナル	macOS: Terminal/iTerm2、Windows: PowerShell
Git	インストール済み

APIキーは環境変数で扱います。記事やGitリポジトリには書かない前提で進めます。

共通セットアップをする

Mac

Macでは、Homebrewを使うなら次のように準備できます。

brew install git python node
python3 --version
node --version
git --version

作業用のディレクトリも作っておきます。

mkdir -p ~/dev/agent-playground
cd ~/dev/agent-playground

Windows

Windowsでは、PowerShellを開いてwingetで必要なツールを入れます。

winget install Git.Git
winget install Python.Python.3.12
winget install OpenJS.NodeJS.LTS

新しいPowerShellを開き直して確認します。

python --version
node --version
git --version

こちらも作業用ディレクトリを作っておきます。

mkdir $HOME\dev\agent-playground
cd $HOME\dev\agent-playground

OpenAI Agents SDKで最小構成を作る

1. Python仮想環境を作る

Mac:

mkdir openai-agent-basic
cd openai-agent-basic
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Windows:

mkdir openai-agent-basic
cd openai-agent-basic
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

PowerShellで仮想環境の有効化がブロックされる場合は、現在ユーザーにだけ実行ポリシーを設定します。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

2. SDKをインストールする

pip install openai-agents

Windowsでも、仮想環境を有効化したPowerShellで同じコマンドを実行します。

pip install openai-agents

3. APIキーを設定する

Mac:

export OPENAI_API_KEY="sk-..."

Windows:

$env:OPENAI_API_KEY="sk-..."

永続化する場合は、OSの環境変数設定や1Password CLIなどを使うのがおすすめです。.env に保存する場合も、忘れずに .gitignore に入れてください。

4. 最小Agentを書く

main.py を作成します。

from agents import Agent, Runner


agent = Agent(
    name="sre_study_agent",
    instructions=(
        "あなたはSRE初学者を支援するAgentです。"
        "難しい用語は短く言い換え、最後に次の学習ステップを3つ提示してください。"
    ),
)


result = Runner.run_sync(
    agent,
    "SLOとSLIの違いを、Web API運用の例で紹介してください。",
)

print(result.final_output)

実行します。

python main.py

Windows:

python .\main.py

ここまでで、OpenAI Agents SDK側の最小構成は動くはずです。

Google ADKで最小構成を作る

1. Python仮想環境を作る

Mac:

cd ~/dev/agent-playground
mkdir google-adk-basic
cd google-adk-basic
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

Windows:

cd $HOME\dev\agent-playground
mkdir google-adk-basic
cd google-adk-basic
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

2. ADKをインストールする

pip install google-adk

Windows:

pip install google-adk

3. APIキーを設定する

Google AI StudioのAPIキーを使う場合は、まず現在のターミナルで動作確認用に環境変数を設定しておきます。

Mac:

export GOOGLE_API_KEY="..."

Windows:

$env:GOOGLE_API_KEY="..."

Google Cloud / Agent Platformを使う場合は、プロジェクトや認証の設定が別途必要になります。最初はGoogle AI StudioのAPIキーでローカル動作を確認し、あとでGoogle Cloud連携へ進める流れが楽でした。

4. ADKのAgentプロジェクトを作る

ADKでは、adk create でAgentプロジェクトの雛形を作れます。ここは公式Quickstartの流れに寄せます。

Mac:

adk create sre_helper

Windows:

adk create sre_helper

作成後、構成はだいたい次のようになります。

sre_helper/
  agent.py
  .env
  __init__.py

ADKのQuickstartでは、作成されたAgentプロジェクトの .env にAPIキーを書きます。ここでは sre_helper/.env に設定してみます。

Mac:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > sre_helper/.env

Windows PowerShell:

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > sre_helper/.env

次に、sre_helper/agent.py を編集します。まずはツールなしの、本当に小さいAgentにしておきます。

from google.adk.agents.llm_agent import Agent


root_agent = Agent(
    name="sre_helper",
    model="gemini-flash-latest",
    description="SREとインフラ運用の学習を支援するAgent",
    instruction=(
        "あなたはSREとインフラ運用に詳しいAgentです。"
        "回答は、概要、具体例、注意点、次の一手の順でまとめてください。"
    ),
)

5. ローカルで起動する

ADKのWeb UIを使う場合は、Agentフォルダの親ディレクトリで実行します。

adk web --port 8000

Windows:

adk web --port 8000

ブラウザで表示されるローカルURLを開き、sre_helper Agentを選んで質問します。

ADK Webは開発・デバッグ用です。本番公開用のUIではないため、チームやCIから利用する場合は後述のCloud RunやAgent RuntimeなどにAPIとしてデプロイする構成を考えます。

CLIで実行する場合:

adk run sre_helper

Windows:

adk run sre_helper

たとえば次のように聞いてみます。

Kubernetes運用でSLOを決めるとき、最初に見るべきメトリクスを紹介してください。

デプロイするときの選択肢

ローカルでAgentを作ったあと、誰かに使ってもらう、CIから呼び出す、業務フローへ組み込む、という段階になるとデプロイ先を考える必要が出てきます。

ADKの公式ドキュメントを見ると、主なデプロイ先として Agent Runtime on Agent Platform、Cloud Run、GKE、その他のコンテナ実行環境が紹介されていました。

選択肢	向いているケース	注意点
ローカル実行	個人開発、検証、プロンプト調整	他メンバーやCIからは使いにくい
Cloud Run	HTTP APIとして軽く公開したい、GitHub ActionsなどCIから呼びたい	認証、Secret Manager、権限設計が必要
Agent Runtime on Agent Platform	Google Cloud上でAgentをマネージドに運用したい	Google Cloud前提の設計に寄せる必要がある
GKE	既存のKubernetes運用基盤に載せたい、ネットワークや実行環境を細かく制御したい	運用負荷はCloud Runより高い
その他のコンテナ基盤	オンプレ、閉域、別クラウドで動かしたい	ADKの便利なデプロイコマンドより自前設計が増える

Cloud Runにデプロイする場合

PythonのADK Agentは、adk deploy cloud_run でCloud Runへデプロイできます。公式ドキュメントではPythonの場合、このコマンドが案内されています。

export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export AGENT_PATH="./sre_helper"
export SERVICE_NAME="sre-helper-agent"

gcloud auth login
gcloud config set project "$GOOGLE_CLOUD_PROJECT"

adk deploy cloud_run \
  --project="$GOOGLE_CLOUD_PROJECT" \
  --region="$GOOGLE_CLOUD_LOCATION" \
  --service_name="$SERVICE_NAME" \
  "$AGENT_PATH"

Cloud Runで公開する場合、最初は認証必須にします。CIや社内ツールから呼ぶ場合も、公開URLを誰でも叩ける状態にするより、Workload Identity Federationやサービスアカウントを使って認証付きで呼ぶ構成にしたいです。

また、APIキーは環境変数に直書きせず、Secret Managerから渡す構成にします。

GitHub ActionsのレビューAgentとして使う場合

たとえばPull Requestの差分をAgentに渡して、SRE観点、セキュリティ観点、運用観点のレビューコメントを作らせたい場合は、次の構成が扱いやすいです。

GitHub Pull Request
  -> GitHub Actions
  -> Cloud Run上のADK Agent API
  -> レビュー結果をPRコメント or job summaryへ出力

この構成にすると、GitHub Actions側にAgentの依存関係やAPIキーを大量に持たせず、Agentの実行環境をCloud Run側に閉じ込められます。

最初の設計では、Agentにリポジトリの書き込み権限を渡さず、レビュー結果を返すだけにしたいです。PRコメントを書き込む場合も、GitHub Actions側で内容を確認してから投稿する形にすると責務が分かれます。

Agent Runtime on Agent Platformを使う場合

Agent Runtime on Agent Platformは、ADKなどで作ったAgentをGoogle Cloud上で管理・スケールさせたい場合の選択肢です。

Cloud RunよりもAgent運用に寄ったマネージドな選択肢なので、セッション、運用、Google Cloud連携を重視する場合はこちらを検討します。一方で、単純なHTTP APIとしてCIから呼びたいだけなら、まずCloud Runで十分なことも多いです。

GKEやその他コンテナ基盤を使う場合

すでにKubernetes基盤があり、NetworkPolicy、Service Mesh、独自の監視、閉域接続などを細かく制御したい場合はGKEが候補になります。

ADK公式ドキュメントではGKEデプロイも案内されています。ただし、最初に選ぶには少し重めです。自分なら、最初はローカル、次にCloud Run、本格運用で必要になったらGKE、くらいの順番で考えます。

書きながら見直したポイント

公開前に、少し厳しめに見直したポイントも残しておきます。

気になった点	直したこと
ADKのPython要件が曖昧	公式Quickstartに合わせてPython 3.10以上、記事では3.11以上推奨に修正
ADKの作成手順が自己流に見える	`adk create`、`root_agent`、`.env`、`adk run`、`adk web` の公式手順に寄せた
`adk web` が本番利用できるように見える	開発・デバッグ用であり、本番はCloud Run等を使う旨を追記
ローカル開発後の道筋がない	Cloud Run、Agent Runtime on Agent Platform、GKE、その他コンテナ基盤の比較を追加
CIレビューAgentの運用像がない	GitHub ActionsからCloud RunのAgent APIを呼ぶ構成を追加
秘密情報の扱いが薄い	Cloud RunではSecret Manager利用を推奨する説明を追加

最初に作るならこのあたり

初回のAgentは、小さく作るのが大事です。SREやインフラエンジニアなら、次のようなテーマが向いています。

テーマ	最初の入力	最初の出力
Runbook検索Agent	障害内容、サービス名	関連Runbook候補と確認手順
Kubernetes調査Agent	`kubectl get events` の結果	怪しいEventと次に見るコマンド
証明書期限チェックAgent	証明書一覧CSV	期限が近い証明書と更新優先度
WAF/CDN変更レビューAgent	変更依頼文	リスク、確認項目、承認前チェック
SLO設計補助Agent	サービス概要	候補SLI、測定方法、注意点

最初から本番環境を操作させる必要はないと思っています。まずは読取り専用の情報を渡して、判断と要約だけを任せるところから始めたいです。

実装時の注意点

Agentにいきなり更新操作をさせない

Agent開発で怖いのは、意図しない操作です。

最初は、CLIやAPIを使うToolも読取り専用にしたいです。更新系の操作を入れる場合は、人間の承認ステップを挟むつもりです。

出力形式を固定する

出力が毎回バラバラだと、レビューも自動化も難しくなります。

たとえば、障害調査Agentなら次のような形式に固定しておくと扱いやすいです。

## 可能性が高い原因
## 根拠
## 次に確認するコマンド
## 影響範囲
## 人間が判断すべきこと

評価データを最初から残す

Agentは「動いた」で終わりにすると、すぐに品質が分からなくなります。

最初から、入力、期待する出力、実際の出力、評価メモを残しておくと改善しやすいです。OpenAI AgentKitのEvalsや、ADK周辺の評価機能につなげる前段としても役に立ちます。

トラブルシューティング

`ModuleNotFoundError` が出る

仮想環境が有効化されていない可能性があります。

Mac:

source .venv/bin/activate
pip list

Windows:

.\.venv\Scripts\Activate.ps1
pip list

APIキーが読み込まれない

同じターミナルで環境変数を設定しているか確認します。

Mac:

echo $OPENAI_API_KEY
echo $GOOGLE_API_KEY

Windows:

echo $env:OPENAI_API_KEY
echo $env:GOOGLE_API_KEY

Windowsでスクリプトが実行できない

PowerShellの実行ポリシーでブロックされている可能性があります。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

会社PCの場合は、社内ポリシーに従ってください。

まとめ

今回は、Agent開発の基礎用語と、OpenAI Agents SDK / Google ADK の環境構築を整理してみました。

自分の中では、ひとまず次の3つで理解しました。

Agentは、モデル、指示、ツール、ループ、安全策、観測性で考えると整理しやすい
OpenAI側はAgentKit全体を意識しつつ、コードファーストならAgents SDKから始めると分かりやすい
Google Cloud側はADKでローカル実行し、あとからCloud Run / Agent Runtime / GKEへ広げられる

次回は、SREやインフラエンジニア向けに、Runbook調査AgentまたはKubernetes障害調査Agentの最小構成を作ってみたいです。

参考資料