OpenAI Agents SDK入門2026｜使い方と実装例

AIエージェント開発のフレームワークが乱立する2026年、OpenAIが出した答えは「とにかく薄く作る」だった。OpenAI Agents SDKは、Agent・Tool・Handoffという3つのプリミティブだけでマルチエージェントを組める軽量フレームワークで、2025年3月のリリースからPyPI月間3,900万DLを超えるまでに成長している。

2026年4月の大型アップデートでSandbox Agents（隔離ワークスペース実行）とModel-Native Harness（モデル主導のツール呼び出し制御）が加わり、プロトタイプ専用だった立ち位置が本番運用レベルに一気に引き上がった。LangGraphやCrewAIと何が違うのか、実際にどう使うのか、コストはいくらかかるのか。元SIerでいまAI系フリーランスをやっている筆者が、Python・TypeScript両方のコードを動かしながら整理した。

OpenAI Agents SDKとは何か

OpenAI Agents SDKは、OpenAIが公式に提供するAIエージェント構築フレームワークだ。前身のSwarm（2024年実験版）を本番向けに再設計したもので、Apache 2.0ライセンスのオープンソースとして公開されている。Python版とTypeScript版の2言語で提供され、OpenAI以外のモデル（LiteLLM経由で100以上）でも動作する。

Swarmから何が変わったか

Swarmは「エージェント間のHandoff」というアイデアを検証するための実験的リポジトリだった。プロダクションで使うには状態管理もトレーシングもなく、エラーが起きたら最初からやり直し。正直、社内PoC以上の用途では厳しかった。

Agents SDKでは以下が根本的に変わった。

• 組み込みTracing: OpenAI Dashboardで各ステップの入出力・トークン消費・レイテンシを可視化
• Guardrails: 入出力のバリデーションをパイプライン内に宣言的に挟める
• Session Persistence: 会話状態をスナップショットし、コンテナが落ちても復元可能
• Sandbox Agents: ファイル操作やシェル実行を隔離コンテナ内で安全に実行

2026年4月アップデートの核心

2026年4月のv0.14で、Agents SDKの位置づけが変わった。プロトタイプ専用だったフレームワークにModel-Native Harnessが載った。従来はアプリケーション側がツール呼び出しのループを管理していたが、Harnessではモデル自身がファイルシステム・Git・シェルと直接やり取りする。

料金体系と必要なコスト

Agents SDK自体は無料。コストはバックエンドのLLM API呼び出しに対してかかる。エージェントが複数ステップを踏むほどトークン消費が積み上がるため、単発のチャットAPIより費用設計が重要になる。

API利用料の目安

エージェントは1タスクあたり5〜20回のAPI呼び出しを行うことが多い。GPT-4.1 miniを使った場合、1タスクあたりの入出力合計が約5万トークンとすると、コストは約$0.05（約7円）。月1,000タスク処理しても7,000円程度に収まる計算だ。

Sandbox利用時の追加コスト

Sandbox Agentsを使う場合、コンテナの起動・維持にResponses APIの標準料金が適用される。Sandboxセッション自体に追加課金はないが、ファイル操作やシェルコマンドの実行結果がコンテキストに載るため、トークン消費は通常の1.5〜2倍になる傾向がある。

筆者がコードレビューエージェントをSandboxで回した検証では、1PRあたり約8万トークン消費でGPT-4.1 mini利用時に$0.08前後だった。月200PR処理で$16。人間のレビュー工数を考えれば十分にペイする水準。

環境構築とインストール手順

セットアップは拍子抜けするほどシンプルだ。依存ライブラリが少ないのはSwarm時代から受け継いだ設計思想で、LangChainのように大量のサブパッケージをインストールする必要はない。

Python版（v0.14+）

Python 3.10以上が必要。仮想環境を作ってからインストールする。

# 仮想環境の作成・有効化
python -m venv .venv
source .venv/bin/activate

# Agents SDKのインストール
pip install openai-agents

# 音声機能が必要な場合
pip install 'openai-agents[voice]'

# APIキーの設定
export OPENAI_API_KEY="sk-..."

TypeScript版

Node.js 18以上が必要。zodがバリデーションに使われるため一緒にインストールする。

# パッケージのインストール
npm install @openai/agents zod

# 環境変数の設定
export OPENAI_API_KEY="sk-..."

3つの基本概念を押さえる

Agents SDKの設計は潔い。覚えるべき概念はAgent、Tool、Handoffの3つだけ。LangChainのChain/Memory/Retriever/Callback/OutputParserのように抽象レイヤーが積み重なることはない。

GuardrailsとTracing

3つのコア概念に加えて、本番運用に欠かせない補助機能が2つある。

Guardrailsは入出力のバリデーション層。ユーザー入力に個人情報が含まれていないかチェックしたり、出力が企業ポリシーに違反していないか検証したりする。パイプラインの前後に宣言的に挟めるので、ビジネスロジックと分離できる。

Tracingは全ステップのログを自動記録する。OpenAI Dashboardで各ツール呼び出しの入出力・トークン消費・レイテンシを確認し、そのままFine-tuningの学習データとしてエクスポートもできる。ログ基盤を自前で組まなくていい分、立ち上がりが速い。

実装例：最初のエージェントを動かす

概念だけ並べても手が動かない。

単一エージェント：天気取得Bot

まずは最小構成。1つのAgentに1つのToolを持たせて同期実行する。

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    """指定都市の天気を返す"""
    # 本番ではAPI呼び出しに置き換え
    return f"{city}の天気: 晴れ、25℃"

agent = Agent(
    name="WeatherBot",
    instructions="ユーザーの質問に日本語で答えてください。",
    tools=[get_weather],
    model="gpt-4.1-mini",
)

result = Runner.run_sync(agent, "東京の天気を教えて")
print(result.final_output)
# → 東京の天気は晴れで、気温は25℃です。

たった15行。@function_toolデコレータで関数をToolに変換し、Agentのtoolsに渡すだけ。型アノテーションからJSONスキーマが自動生成されるため、スキーマを手書きする必要がない。

マルチエージェント：トリアージ＋専門Agent

Handoffを使って、問い合わせ内容に応じて適切な専門Agentにルーティングする構成。カスタマーサポートの典型パターンだ。

from agents import Agent, Runner

billing_agent = Agent(
    name="BillingAgent",
    instructions="請求・支払いに関する質問に対応してください。",
    model="gpt-4.1-mini",
)

tech_agent = Agent(
    name="TechAgent",
    instructions="技術的な質問に対応してください。",
    model="gpt-4.1-mini",
)

triage_agent = Agent(
    name="TriageAgent",
    instructions="""ユーザーの問い合わせを分類し、
    適切な担当にハンドオフしてください。
    - 請求・支払い → BillingAgent
    - 技術的な質問 → TechAgent""",
    handoffs=[billing_agent, tech_agent],
    model="gpt-4.1-mini",
)

result = Runner.run_sync(
    triage_agent,
    "先月の請求書が二重に来ているのですが"
)
print(result.final_output)
# → BillingAgentが応答

トリアージAgentのhandoffsに専門Agentのリストを渡すだけで、ルーティングロジックはLLMが判断する。条件分岐をif文で書く必要がない。ここが従来のルールベースのチャットボットとの決定的な違いだ。

TypeScript版の書き方

TypeScript版はZodによる型安全なTool定義が特徴。Python版とAPI設計は揃えてあるので、片方を覚えればもう片方も読める。

import { Agent, run } from "@openai/agents";
import { z } from "zod";

const agent = new Agent({
  name: "Greeter",
  instructions: "ユーザーに日本語で挨拶してください。",
  model: "gpt-4.1-mini",
  tools: [{
    name: "get_user_name",
    description: "ユーザー名を取得する",
    parameters: z.object({ userId: z.string() }),
    execute: async ({ userId }) => {
      return `ユーザー${userId}の名前: 田中太郎`;
    },
  }],
});

const result = await run(agent, "私の名前は？");
console.log(result.finalOutput);

Sandbox Agentsで本番運用に耐える設計

2026年4月アップデートの目玉がSandbox Agents。ファイル操作・Git操作・シェルコマンドの実行を隔離されたコンテナ内で行える仕組みだ。エージェントにrm -rf /を実行されてもホスト環境には影響しない。

Sandboxの3層永続化

Sandbox Agentsでは状態管理が3層構造になっている。

コンテナが突然落ちてもスナップショットから復元できる。大規模コードベースのリファクタリングのような長時間タスクを途中から再開できるのは、従来のエージェント実行にはなかった保証だ。

apply_patchでトークン節約

従来のファイル編集は「500行のファイルを丸ごと出力して上書き」方式だった。2行の修正に500行分のトークンを消費していたわけだ。

Model-Native Harnessのapply_patchはdiff形式で変更箇所だけを送る。Codex CLIで実証済みの手法がSDKに降りてきた形で、トークン消費がファイルサイズに比例しなくなった。500行のファイルの2行修正なら、出力トークンは10分の1以下に収まる。

LangGraph・CrewAIとの比較と選び方

LangGraph、CrewAI、OpenAI Agents SDK。2026年時点でよく名前が挙がる3つだが、設計の出発点がまるで違う。比較表だけ見ても選べないので、設計思想の差から押さえる。

自分ならどれを選ぶか

結論から言うと、自分ならまずOpenAI Agents SDKで動くものを作る。理由は立ち上がりの速さ。100行以下でHandoffパターンまで実装でき、TracingがOpenAI Dashboardに自動で飛ぶので、デバッグ環境を自前で構築する必要がない。

ただし、条件分岐が5つを超えるワークフロー、並列ブランチ+承認ゲートが必要なケース、あるいはOpenAI以外のモデルをメインで使いたい場合はLangGraphの方が適している。グラフ定義の学習コストは高いが、複雑な要件を後から継ぎ足すよりも最初からグラフで設計した方が破綻しにくい。

CrewAIは「営業チームのワークフロー」「コンテンツ制作パイプライン」のようにロールが明確に分かれるケースで光る。GitHub Starsの伸びも早く、MCP対応もファーストクラスなので、エコシステムの勢いは3つの中で最も強い。

実務ユースケース3選

カスタマーサポート、コードレビュー、データ分析。プロトから本番移行までのストーリーが短く、Agents SDKが一番フィットする3領域だ。

1. カスタマーサポート自動化

導入事例の数ではダントツ。トリアージAgent → 専門Agent（請求・技術・返品）というHandoffパターンを組むと、問い合わせの70〜80%を人手なしで捌ける。

Guardrailsで個人情報をマスクし、Tracingで応答品質を監視する。人間のオペレーターが触るのはエスカレーション案件だけ。この運用モデルが急速に広まっている。

2. コードレビュー・修正エージェント

Sandbox Agentsで一気に実用域に入った。PRが飛んできたらSandbox内でクローン → テスト実行 → 修正提案のコメント、まで自動で回る。

OpenAIのCodexが最大規模の実装例。あのSandbox機能をSDKに降ろしたのがv0.14だ。5人チームでもCodex級の自動レビューを自前で組める時代になった。

3. データ分析パイプライン

CSVやスプレッドシートを入力とし、データクリーニング → 分析 → レポート生成を自動化するパターン。各ステップを別Agentに分担させることで、途中でエラーが起きたステップだけ再実行できる。

データ分析の現場では「分析コード自体はPythonで書けるが、データの前処理パターンが毎回微妙に違う」問題がある。Agents SDKでデータの形式判定AgentとクリーニングAgentを分けることで、新しいデータソースにも柔軟に対応できる。関連するデータ分析のキャリアについてはデータサイエンティスト転職ガイドも参考になる。

つまずきポイントと対処法

ただし、どのパターンも最初の1週間は同じ問題で詰まる。

Handoffの無限ループ

Agent AがAgent Bにハンドオフし、BがAに戻す。instructionsの書き方が曖昧だとこのループに陥る。対策は2つ。

• max_turnsパラメータでRunner全体のターン数上限を設定する
• 各Agentのinstructionsに「ハンドオフ先から戻ってきた場合は直接回答する」と明記する

トークン消費の想定外の膨張

エージェントが10ステップ以上動くと、会話履歴がコンテキストに蓄積されてトークン消費が爆発する。GPT-4.1の128Kコンテキストを使い切るケースも珍しくない。

対策として、Runner.runにmax_turns=10を設定するか、途中でコンテキストを要約するカスタムToolを挟む。コスト管理の基本はAI API料金比較2026の記事で各モデルの単価を比較しているので参照してほしい。

TypeScript版とPython版の機能差

2026年5月時点で、Sandbox AgentsとModel-Native HarnessはPython版のみ。TypeScript版はコアのAgent・Tool・Handoff・Tracing機能は揃っているが、Sandbox対応はロードマップ上の「coming soon」のまま。

TypeScriptでサーバーレスAPIを書いてフロントエンドと統合したい場合は、Sandbox抜きの構成で先に進める。Sandbox機能が必要ならPython版でバックエンドサービスを切り出す設計も現実的な選択肢だ。

まとめ：Agents SDKで始めるAIエージェント開発

最初はAgents SDKで組む。それだけだ。Agent・Tool・Handoffを覚えれば100行以下でHandoffパターンまで動く。TracingがOpenAI Dashboardに自動で飛ぶので、ログ基盤を自前で立てる時間もかからない。

条件分岐が5本を超えたらLangGraphへの切り替えを検討する。ただし、そこまで複雑なワークフローが本当に必要かどうか、まずAgents SDKで動かしながら確認する方が設計ミスは少ない。GPT-4.1 miniなら1タスク7円。月1,000タスクでも7,000円。動かしながら考えられるコストだ。

エージェント全般の知識はAIエージェント完全ガイド2026で固められる。OpenAI以外のフレームワークとも比較したい場合はClaude Agent SDK入門を読んでから判断しても遅くない。プロンプト設計の基礎はプロンプトエンジニアリング入門が役立つ。