結論: OpenAI Agents SDK（v0.15系、2026年5月時点）は、Handoffs・Guardrails・Tracing・Sandbox実行の4機能を中核に据えた、OpenAIモデル専用のマルチエージェント開発フレームワークです。GitHub Stars 25.9k、最短10行でエージェントが動くシンプルさが最大の強みです。
この記事の要点:
- 要点1: Agents SDK v0.15.3（2026年5月6日リリース）はSandbox実行・Model-Native Harnessを追加し、ファイル操作・コード実行を伴う長期タスクに対応
- 要点2: GPT-5.5（gpt-5.5）がデフォルト推奨モデルに昇格。入力$5.00/1M・出力$30.00/1Mトークンで、GPT-4.1比で推論品質が大幅向上
- 要点3: LangGraph・Claude Agent SDK・AWS Bedrock AgentCore SDKとの使い分けを比較表つきで解説し、選定基準を明確化
対象読者: マルチエージェントシステムの実装を検討中のAIエンジニア・DX推進担当者・技術経営者
読了後にできること: pip install openai-agents から最初のマルチエージェント構成を動かし、Tracing Dashboardで動作を可視化する
「マルチエージェントって結局、どのSDKで作ればいいんですか？」
企業向けAI研修で、ここ数ヶ月で急増している質問です。AWS Bedrock AgentCore、Claude Agent SDK、LangGraph、そしてOpenAI Agents SDK——選択肢が増えすぎて、どれを選べばいいか分からないという声をよく聞きます。
正直に言うと、全部「正解」なんです。ただ、向いている用途が違う。研修先のエンジニアチームが迷ったとき、私が真っ先に勧めるのがOpenAI Agents SDKです。理由はシンプルで、「10行で動く」から。プロトタイプから本番まで同じフレームワークで完結できるのは、開発速度を最優先する企業にとって大きなメリットなんです。
この記事では、OpenAI Agents SDK v0.15系（2026年5月最新）の全機能——Agents・Handoffs・Guardrails・Tracing・Sandbox——を、コピペ可能なPythonコードつきで解説します。さらに、他SDKとの比較表・GPT-5モデル対応・2026年4月の最新アップデートまで網羅します。今日から実装を始められる内容にしていますので、ぜひ手を動かしながら読んでください。
まず動かす：5分で最初のマルチエージェントを作る
理論より先に動くもの。まずインストールから最初のHandoff（エージェント間移譲）まで5分で確認しましょう。
インストール
# 基本インストール
pip install openai-agents
# 音声エージェント対応版
pip install 'openai-agents[voice]'
# uv使用の場合（2026年推奨）
uv add openai-agentsHello Multi-Agent（最小構成）
import os
from agents import Agent, Runner
# 環境変数にAPIキーを設定
os.environ["OPENAI_API_KEY"] = "your-api-key"
# エージェント定義（デフォルトモデルはgpt-4.1）
agent = Agent(
name="アシスタント",
instructions="あなたは親切な日本語アシスタントです。",
model="gpt-4.1"
)
# 同期実行
result = Runner.run_sync(agent, "AIエージェントとは何ですか？1文で教えてください。")
print(result.final_output)
実行結果はこれだけで出てきます。次に、実際のマルチエージェント構成（Handoffs）を見てみましょう。
Handoffつきのマルチエージェント構成（5分実装）
from agents import Agent, Runner, handoff
# 専門エージェントを定義
billing_agent = Agent(
name="請求担当エージェント",
instructions="請求・支払い関連の質問に回答します。",
model="gpt-4.1-mini"
)
support_agent = Agent(
name="技術サポートエージェント",
instructions="技術的な問題のトラブルシューティングを行います。",
model="gpt-4.1-mini"
)
# トリアージエージェント（窓口）
triage_agent = Agent(
name="トリアージエージェント",
instructions="""
ユーザーの質問を分析し、適切なエージェントに転送してください。
- 請求・支払い関連 → 請求担当エージェント
- 技術的な問題 → 技術サポートエージェント
不明な場合は自分で回答してください。
""",
handoffs=[billing_agent, handoff(support_agent)]
)
# 実行
result = Runner.run_sync(triage_agent, "先月の請求書が届いていません")
print(result.final_output)
これだけでハンドオフが機能するんです。実際に研修先でこのコードを見せると、「え、これだけですか？」と驚かれることが多いです。LangGraphのグラフ定義に比べると、圧倒的にシンプルです。
AIエージェントの基本概念や導入ステップについては、AIエージェント導入完全ガイドで体系的にまとめています。マルチエージェント実装の前にアーキテクチャを理解したい方はまずこちらをどうぞ。
OpenAI Agents SDKの4大コア機能を徹底解説
SDK全体の設計思想は「少ないプリミティブで、すぐ使える、でもカスタマイズもできる」です。4つのコア機能を順番に見ていきます。
1. Agents（エージェント定義）
Agentクラスが中心。インストラクション・モデル・ツール・ハンドオフ先・ガードレールを一箇所で定義します。
from agents import Agent
from pydantic import BaseModel
# 出力スキーマを定義（構造化出力）
class SummaryOutput(BaseModel):
summary: str
key_points: list[str]
action_items: list[str]
# フル定義版エージェント
analysis_agent = Agent(
name="業務分析エージェント",
instructions="""
提供されたビジネス文書を分析し、以下を日本語で出力してください：
1. 要約（3文以内）
2. 重要ポイント（最大5点）
3. アクションアイテム
数字と固有名詞は、根拠（出典/計算式）を添えてください。
""",
model="gpt-5.5", # 高品質が必要な場合はGPT-5.5を指定
output_type=SummaryOutput, # 構造化出力
)
モデルは記事ごとに指定できます。コスト最適化では「高コストなGPT-5.5は最終判断エージェントのみ、中間処理はgpt-4.1-mini」という使い分けが実務でよく見られるパターンです。
2. Handoffs（エージェント間の引き継ぎ）
HandoffsはSDKの中で最もユニークな機能です。エージェントが別のエージェントに制御を移譲する仕組みで、LLMにはツールとして見えます。
たとえば「Refund Agent」へのHandoffは、LLM視点ではtransfer_to_refund_agentというツール呼び出しとして表現されます。これにより、モデルが状況を判断して自律的に引き継ぎ先を選択します。
from agents import Agent, handoff
from pydantic import BaseModel
# 引き継ぎ時のメタデータ定義
class EscalationData(BaseModel):
reason: str
priority: int # 1-5
# コールバック付きHandoff（引き継ぎ時にログを残す）
def on_escalate(data: EscalationData):
print(f"[HANDOFF] 優先度{data.priority}: {data.reason}")
# ここにSlack通知やDB記録を追加
senior_agent = Agent(
name="上位エスカレーションエージェント",
instructions="複雑・高優先度の案件を処理します。"
)
first_line_agent = Agent(
name="一次対応エージェント",
instructions="""
一般的な問い合わせに対応します。
複雑または優先度の高い案件は上位エージェントに引き継いでください。
引き継ぎ時は必ず理由と優先度を明記してください。
""",
handoffs=[
handoff(
senior_agent,
input_type=EscalationData,
on_handoff=on_escalate
)
]
)
ポイントはon_handoffコールバック。引き継ぎのたびにSlack通知・DB記録・監査ログを自動で残せます。エンタープライズ用途で監査証跡が必要な場合に便利です。
3. Guardrails（入出力ガードレール）
Guardrailsは安全性確保のための仕組みです。入力ガードレール（Input Guardrails）と出力ガードレール（Output Guardrails）の2種類があります。
研修先で最もよく使われるパターンは「コスト保護型ガードレール」です。高価なGPT-5.5を使う前に、安価な小型モデルで不適切な入力を弾きます。
from agents import Agent, Runner, input_guardrail, GuardrailFunctionOutput
from pydantic import BaseModel
class GuardrailResult(BaseModel):
is_safe: bool
reason: str
# ガードレール用の軽量エージェント（安価モデルで高速チェック）
guardrail_agent = Agent(
name="入力検証エージェント",
instructions="""
ユーザーの入力が以下に該当する場合、is_safe=Falseを返してください：
- 個人情報（氏名・住所・クレジットカード番号など）
- 不適切なコンテンツ
- 業務と無関係なリクエスト
それ以外はis_safe=Trueを返してください。
""",
output_type=GuardrailResult,
model="gpt-4.1-mini" # 軽量モデルで高速・安価にチェック
)
@input_guardrail
async def safety_check(ctx, agent, input):
result = await Runner.run(guardrail_agent, input, context=ctx.context)
output = result.final_output_as(GuardrailResult)
return GuardrailFunctionOutput(
output_info=output,
tripwire_triggered=not output.is_safe
)
# 本番エージェントにガードレールを適用
main_agent = Agent(
name="業務エージェント",
instructions="社内業務の質問に回答します。",
model="gpt-5.5", # 本番は高品質モデル
input_guardrails=[safety_check]
)
# 実行（不適切な入力は自動でブロック）
try:
result = Runner.run_sync(main_agent, "山田太郎の住所を教えてください")
except Exception as e:
print(f"ガードレール作動: {e}")
入力ガードレールはデフォルトで並列実行されます。エージェントと同時に動くため、ガードレールが問題を検知するとすぐに処理を中断。トークンの無駄遣いを防げます。ブロッキングモード（先にチェック完了してからエージェントを起動）も選べます。
4. Tracing（トレース・デバッグ）
Tracingは本番運用で最も重要な機能です。エージェントの全行動を自動記録し、OpenAI Traces Dashboard（platform.openai.com/traces）で可視化できます。
import asyncio
from agents import Agent, Runner, trace, flush_traces
# 複数ステップのワークフローをトレース
async def run_research_workflow(topic: str):
with trace("リサーチワークフロー"):
# ステップ1: リサーチ
research_agent = Agent(
name="リサーチエージェント",
instructions="指定トピックの情報を収集・整理します。"
)
research_result = await Runner.run(research_agent, f"トピック: {topic}")
# ステップ2: 要約
summary_agent = Agent(
name="要約エージェント",
instructions="リサーチ結果を経営者向けに要約します。"
)
summary_result = await Runner.run(
summary_agent,
f"以下のリサーチ結果を要約してください:n{research_result.final_output}"
)
return summary_result.final_output
# バックグラウンドジョブ（Celery等）での使用
def celery_task(topic: str):
try:
with trace("celery_research_task"):
result = asyncio.run(run_research_workflow(topic))
return result
finally:
flush_traces() # 必須：バックグラウンドジョブでは明示的にflush
Tracingはデフォルトでオンです。無効化したい場合はOPENAI_AGENTS_DISABLE_TRACING=1環境変数を設定します。個人情報を扱う場合はtrace_include_sensitive_data=FalseでLLMの入出力をトレースに含めないよう設定できます。
サードパーティ統合も充実。Weights & Biases、Langfuse、MLflow、Datadog、Braintrust等、25以上のプラットフォームと連携できます。
2026年4月の最新アップデート：Sandbox AgentとModel Harness
2026年4月15日、OpenAIはAgents SDKの大型アップデートを発表しました。「エンタープライズが求める長時間タスクへの対応」がテーマです。
Sandbox Agent（サンドボックス実行）
エージェントが安全な隔離環境（サンドボックス）内でファイル操作・コマンド実行・コード実行を行える機能です。
from agents.sandbox import SandboxAgent
# サンドボックス内でコードを自律実行するエージェント
sandbox_agent = SandboxAgent(
name="コード実行エージェント",
instructions="""
与えられたタスクを完了するために、以下の操作が可能です：
- ファイルの読み書き
- コマンドの実行
- コードのテスト・修正
長期タスクも途中で再開できます。
""",
model="gpt-5.5"
)
# リポジトリの分析タスク（時間のかかる処理も対応）
result = sandbox_agent.run_sync(
"このPythonプロジェクトのコードを分析し、バグを修正してテストを実行してください"
)
対応サンドボックスプロバイダーは：E2B・Modal・Runloop・Blaxel・Cloudflare・Daytona・Vercel。「Bring Your Own Sandbox」として自社環境も利用可能です。現時点ではPython版のみ対応、TypeScript版は後日リリース予定です。
Model-Native Harness（モデルネイティブハーネス）
設定可能なメモリ・サンドボックス対応オーケストレーション・Codexスタイルのファイルシステムツール・フロンティアエージェントに共通するプリミティブとの標準統合を提供します。長時間・複数ステップのタスクでも一貫した実行環境を維持できます。
対応モデルと料金：GPT-5系の選び方
SDK v0.15系で使用可能なモデルと料金（2026年5月時点・公式価格）です。
| モデル | 入力 | 出力 | 推奨用途 |
|---|---|---|---|
| gpt-5.5 | $5.00/1Mトークン | $30.00/1Mトークン | 最終判断・高品質出力が必要なエージェント |
| gpt-5-mini | $0.40/1Mトークン | $1.60/1Mトークン | 中間処理・高頻度呼び出しエージェント |
| gpt-5-nano | 要確認 | 要確認 | ガードレール・分類等の軽量タスク |
| gpt-4.1 | $2.00/1Mトークン | $8.00/1Mトークン | 低レイテンシが必要なインタラクティブ用途 |
| gpt-4.1-mini | $0.40/1Mトークン | $1.60/1Mトークン | コスト最適化・大量処理 |
| gpt-realtime-1.5 | リアルタイム音声 | リアルタイム音声 | 音声エージェント |
実務的な料金最適化パターンとして、「ガードレールにgpt-4.1-mini（安価・高速）、本番エージェントにgpt-5.5（高品質）」という組み合わせが有効です。バッチAPI利用で50%割引も適用できます。
なお、GPT-5をAgent SDKで使用した際の注意点として、「gpt-5は詳細を聞いてからツールを呼ぶ傾向がある」という報告がGitHub Issueに上がっています（Issue #1397）。GPT-4.1に比べてツール呼び出しのタイミングが違うため、インストラクションの調整が必要になるケースがあります。
MCP統合：外部サービスをエージェントに接続する
Agents SDKはModel Context Protocol（MCP）をネイティブサポートしています。GitHub・Google Drive・Slack・データベース等の外部ツールをエージェントに簡単に接続できます。
from agents import Agent, Runner
from agents.mcp import MCPServer, MCPServerStdio
async def run_with_mcp():
# stdio型MCPサーバーを起動（ローカルで動かすケース）
async with MCPServerStdio(
name="ファイルシステムMCP",
params={"command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/tmp/workspace"]}
) as mcp_server:
agent = Agent(
name="ファイル操作エージェント",
instructions="MCPサーバー経由でファイルを操作します。",
mcp_servers=[mcp_server]
)
result = await Runner.run(agent, "workspaceフォルダの内容を一覧表示してください")
print(result.final_output)
# 複数MCPサーバーの一括管理
from agents.mcp import connect_mcp_servers
async def multi_mcp():
servers_info = await connect_mcp_servers([
MCPServerStdio(name="fs", params={"command": "npx", "args": [...]}),
MCPServerStdio(name="slack", params={"command": "npx", "args": [...]}),
])
print(f"接続成功: {servers_info.active}")
print(f"接続失敗: {servers_info.failed}")
MCPは3種類のトランスポートに対応：Hosted MCP（リモートサーバーをツールとして使用）・Streamable HTTP（ローカル/リモート）・stdio（標準入出力）。新規開発ではStreamable HTTPまたはstdioが推奨です。
TypeScript/JavaScript版：フロントエンドへの統合
Python版と並行して、TypeScript/JavaScript版（openai-agents-js）も提供されています。フロントエンド・Node.js環境での利用が可能です。
// TypeScript版のインストール
// npm install @openai/agents
import { Agent, Runner } from '@openai/agents';
// 基本エージェント
const agent = new Agent({
name: 'JA Assistant',
instructions: 'あなたは役に立つ日本語アシスタントです。',
model: 'gpt-4.1'
});
const result = await Runner.run(agent, 'こんにちは');
console.log(result.finalOutput);
現時点でTypeScript版はSandbox Agent・Model-Native Harnessに未対応（後日実装予定）。フル機能が必要な場合はPython版を使用してください。
OpenAI Agents SDK vs 他SDKの徹底比較
直前に公開したClaude Agent SDK完全ガイドと対をなす形で、4大フレームワークを比較します。
| 比較軸 | OpenAI Agents SDK | Claude Agent SDK | LangGraph | AWS Bedrock AgentCore |
|---|---|---|---|---|
| 対応モデル | OpenAIのみ（gpt-4.1, gpt-5.5系） | Claudeのみ（claude-sonnet, opus系） | モデル完全無関係 | Bedrockサポートモデル全般 |
| 学習コスト | 低い（10行で動く） | 低〜中（ツール呼び出しベース） | 高い（グラフ定義が必要） | 中〜高（AWSリソース設定が必要） |
| マルチエージェント構成 | Handoffs（明示的移譲） | サブエージェント呼び出し | グラフノード間の条件分岐 | マルチエージェント協調（Inline/External） |
| 状態管理 | Context変数（エフェメラル） | MCPサーバー経由で永続化 | リデューサーベース（最も高機能） | AWSマネージドメモリ（S3/DynamoDB） |
| 安全機能 | Guardrails（入出力・ツール） | Constitutional AI統合・Extended Thinking | カスタム実装が必要 | IAM/VPCによるエンタープライズ統合 |
| 可観測性 | Traces Dashboard（標準搭載） | Anthropic Console | LangSmith（別サービス） | CloudWatch統合 |
| 本番実績 | 高（GitHubスター25.9k） | 高（安全性重視企業で採用増） | 最高（Klarna・Uber・LinkedIn等） | 高（AWS既存ユーザー中心） |
| Sandbox/ファイル操作 | Sandbox Agent（2026年4月追加） | Computer Use対応 | カスタム実装 | Code Interpreter統合 |
| 料金 | gpt-5.5: $5/$30 per 1M tokens | claude-sonnet: $3/$15 per 1M tokens | モデル料金のみ（SDK自体は無料） | AWS料金体系+モデル料金 |
| 向いている用途 | プロトタイプ〜本番、OpenAI中心スタック | 安全性重視、Anthropic中心スタック | 複雑な条件分岐、モデル非依存 | AWS既存インフラへの統合 |
使い分けの判断フロー
- まずOpenAIモデルで動かしたい・とにかく早く作りたい → OpenAI Agents SDK
- 安全性最優先・医療/金融/法務 → Claude Agent SDK
- 複雑な条件分岐・並列処理・モデル非依存 → LangGraph
- AWS既存インフラへのシームレス統合 → AWS Bedrock AgentCore
実践：エンタープライズ向けマルチエージェントシステムの実装
ここからは、実際に企業導入で使えるレベルのコードを紹介します。「問い合わせ自動対応システム」を例に、Handoffs・Guardrails・Tracingを組み合わせた本格的な構成です。
import asyncio
from agents import Agent, Runner, handoff, input_guardrail, trace, GuardrailFunctionOutput
from pydantic import BaseModel
# === ガードレール定義 ===
class ContentCheck(BaseModel):
is_appropriate: bool
category: str
content_checker = Agent(
name="コンテンツチェッカー",
model="gpt-4.1-mini",
output_type=ContentCheck,
instructions="入力が業務関連かつ適切か判断してください。"
)
@input_guardrail
async def content_guardrail(ctx, agent, input):
result = await Runner.run(content_checker, input, context=ctx.context)
check = result.final_output_as(ContentCheck)
return GuardrailFunctionOutput(
output_info=check,
tripwire_triggered=not check.is_appropriate
)
# === 専門エージェント ===
hr_agent = Agent(
name="人事担当エージェント",
instructions="休暇・給与・福利厚生・採用に関する質問に回答します。",
model="gpt-4.1"
)
it_agent = Agent(
name="IT担当エージェント",
instructions="システムトラブル・アクセス権限・ソフトウェア申請を処理します。",
model="gpt-4.1"
)
general_agent = Agent(
name="一般業務エージェント",
instructions="その他の業務一般に関する質問に回答します。",
model="gpt-4.1-mini"
)
# === トリアージエージェント（窓口）===
class HandoffInput(BaseModel):
reason: str
urgency: int # 1-5
triage_agent = Agent(
name="社内問い合わせ窓口",
instructions="""
社員からの問い合わせを以下のエージェントに振り分けてください：
- 人事関連（休暇・給与・採用）→ 人事担当エージェント
- IT・システム関連 → IT担当エージェント
- その他 → 一般業務エージェント
振り分け時は必ず理由と緊急度（1-5）を指定してください。
不足している情報があれば、最初に質問してから処理を開始してください。
""",
model="gpt-4.1",
input_guardrails=[content_guardrail],
handoffs=[
handoff(hr_agent, input_type=HandoffInput),
handoff(it_agent, input_type=HandoffInput),
handoff(general_agent, input_type=HandoffInput)
]
)
# === 実行（Tracingつき）===
async def handle_inquiry(user_message: str):
with trace("社内問い合わせ対応"):
try:
result = await Runner.run(triage_agent, user_message)
return {"status": "success", "response": result.final_output}
except Exception as e:
return {"status": "guardrail_triggered", "error": str(e)}
# テスト実行
if __name__ == "__main__":
test_cases = [
"来月の有給休暇の残日数を教えてください",
"VPNの接続方法が分かりません",
"会議室の予約方法を教えてください"
]
for query in test_cases:
result = asyncio.run(handle_inquiry(query))
print(f"Q: {query}")
print(f"A: {result}n")
このパターンを研修先の中規模企業（従業員150名）のIT部門で試したところ、問い合わせの一次対応を自動化できた割合が想定より高かったです。ただし、「正式な人事手続き」「セキュリティインシデント」については必ず人間のエスカレーションが入るよう、Handoffの先に人間介在フローを追加することを強くお勧めします。
非同期処理とSession管理の実装パターン
本番環境では非同期実行とSessionによる会話履歴管理が不可欠です。
import asyncio
from agents import Agent, Runner, Session
# Session IDでユーザーごとの会話履歴を管理
async def chat_with_memory(user_id: str, message: str):
agent = Agent(
name="記憶あり会話エージェント",
instructions="ユーザーとの会話履歴を踏まえて回答します。"
)
# Session IDでユーザー別の履歴を自動管理
session = Session(session_id=f"user_{user_id}")
result = await Runner.run(
agent,
message,
session=session
)
return result.final_output
# 並列実行（複数ユーザーの問い合わせを同時処理）
async def process_multiple_inquiries(inquiries: list[dict]):
tasks = [
chat_with_memory(item["user_id"], item["message"])
for item in inquiries
]
results = await asyncio.gather(*tasks)
return results
# 使用例
inquiries = [
{"user_id": "001", "message": "先ほど確認していた予算について続きを教えてください"},
{"user_id": "002", "message": "昨日の研修の内容を復習したい"},
]
results = asyncio.run(process_multiple_inquiries(inquiries))
Sessionは会話履歴を自動管理します。「先ほど確認していた件」のような文脈依存の質問にも、ユーザーIDをキーに履歴を引き継いで回答できます。
【要注意】OpenAI Agents SDKのよくある落とし穴と回避策
研修やコンサルティングで実際に見かけた失敗パターンを公開します。
失敗1：APIキーをコードにハードコードする
❌ 絶対NG：os.environ["OPENAI_API_KEY"] = "sk-proj-xxxxx"とコードに書く
⭕ 正しいアプローチ：
# .envファイル（.gitignoreに追加すること）
# OPENAI_API_KEY=sk-proj-xxxxx
from dotenv import load_dotenv
import os
load_dotenv()
# 環境変数は自動的に agents SDK が読み込む
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise ValueError("OPENAI_API_KEY が設定されていません")
GitHubにAPIキーをpushしてしまうと、数分以内にbotに検出されてキーが無効化されます。企業の本番環境ではAWS Secrets ManagerやAzure Key Vaultなどのシークレット管理サービスを使ってください。
失敗2：すべてのエージェントに高価なモデルを使う
❌ コスト爆発パターン：全エージェントにgpt-5.5を指定する
⭕ コスト最適化パターン：タスクの重要度・複雑度でモデルを分ける
# コスト最適化の基本原則
# ガードレール・分類・ルーティング → gpt-4.1-mini（安価・高速）
# 一般的な回答生成 → gpt-4.1（バランス型）
# 最終判断・複雑な推論 → gpt-5.5（高品質）
guardrail_agent = Agent(model="gpt-4.1-mini", ...) # 安価
routing_agent = Agent(model="gpt-4.1", ...) # バランス
final_agent = Agent(model="gpt-5.5", ...) # 高品質
ガードレール専用エージェントにgpt-5.5を使った結果、コストが想定の10倍になったというケースを実際に見ました。分類・ルーティング系タスクはgpt-4.1-miniで十分すぎるくらい精度が出ます。
失敗3：Handoffループを作ってしまう
❌ 無限ループパターン：Agent AがAgent Bに、Agent BがAgent Aにハンドオフできる構成
⭕ 正しいアプローチ：ハンドオフは原則一方向に設計する
# NG: 循環参照
agent_a = Agent(name="A", handoffs=[agent_b])
agent_b = Agent(name="B", handoffs=[agent_a]) # Aに戻れてしまう
# OK: トリアージ→専門エージェントの一方向
triage = Agent(name="窓口", handoffs=[specialist_a, specialist_b])
specialist_a = Agent(name="専門A") # ハンドオフ先なし（終端）
specialist_b = Agent(name="専門B") # ハンドオフ先なし（終端）
ループが発生するとトークン上限に達してエラーになります。SDKには現在ループ検出機能がないため、設計段階で一方向フローを意識してください。
失敗4：バックグラウンドジョブでflush_tracesを忘れる
❌ トレースがダッシュボードに表示されない：Celery/RQ等のバックグラウンドジョブでtraceを使っているが何も見えない
⭕ 正しいアプローチ：
from agents import flush_traces, trace
def my_celery_task(input_data):
try:
with trace("celery_task"):
result = some_agent_run(input_data)
return result
finally:
flush_traces() # これが必須！忘れるとトレースが送信されない
バックグラウンドジョブはプロセスが終了するとトレースバッファが消えます。finallyブロックでのflush_traces()は必須です。
失敗5：GPT-5をそのまま使って詰まる
❌ gpt-4.1からgpt-5.5に切り替えたらエージェントが止まる
⭕ 対処法：
# gpt-5はツール呼び出しの前に詳細を聞く傾向がある
# インストラクションに「詳細を確認する前にツールを呼んでください」を追加
agent = Agent(
name="アクション指向エージェント",
instructions="""
必要な情報は推測で補完し、すぐにツールを呼び出してください。
ユーザーへの確認は最小限にしてください。
不足情報があっても、まずツールを実行してから結果に基づいて追加質問してください。
""",
model="gpt-5.5"
)
GPT-5はGPT-4.1より慎重で、不明な点を先に確認しようとする傾向があります（GitHub Issue #1397で報告）。インストラクションで「まず動く」ことを明示すると改善します。
あわせて読みたい: 【2026年最新】Vertex AI Agent Builder完全ガイド — Google ADK Python SequentialAgent/ParallelAgent/LoopAgent実装・Agent Engineデプロイ・4大SDK比較表つき
まとめ：今日から始める3つのアクション
- 今日やること:
pip install openai-agentsしてHello Worldを動かす。HandoffのサンプルコードをそのままコピペしてCLIで実行確認。 - 今週中: 自社の繰り返し業務（問い合わせ対応・レポート生成・データ収集など）を1つ選び、3〜5エージェントの構成図を書く。Guardrailsの要件（何をブロックすべきか）を言語化する。
- 今月中: Tracing Dashboardを使って、実際のエージェントの動作をモニタリングしながら本番投入。GPT-4.1でプロトタイプ、品質に問題あればGPT-5.5に切り替えるコスト最適化フローを確立する。
あわせて読みたい:
- Claude Agent SDK完全ガイド2026 — Anthropic SDKとの設計思想の違い・使い分けを詳解。本記事との対比でフレームワーク選定が確実になります。
- AWS Bedrock AgentCore完全ガイド2026 — AWSインフラとの統合、エンタープライズセキュリティ要件への対応を解説。
- AutoGen完全ガイド｜マルチエージェント会話設計
- CrewAI完全ガイド｜役割ベースのマルチエージェント協調設計
- 企業向けAIエージェント基盤5社比較：OpenAI/Microsoft/Google/AWS/Salesforceの導入判断軸
- AIエージェント観測・評価完全ガイド：LangSmith/Langfuse/RAGAS/DeepEvalで本番品質を可視化
- AIエージェントMemory完全ガイド：Mem0/Zep/Lettaで永続記憶を実装、Core/Archival/Recall 3層モデル
- AI Voiceエージェント7強完全比較：Vapi/Retell/ElevenLabs/Deepgramほか電話AI比較
- AIカスタマーサポート7強完全比較：Decagon/Sierra/Intercom Fin等のCS AI基盤比較
- 士業のAI活用完全ガイド：税理士/社労士/弁護士/司法書士/行政書士の実践プロンプト10選
- Codex×経理 自動化プロンプト10選：経理特化10シーンで最大80%削減
- Codex×Excel自動化プロンプト10選：VBA/Apps Script/Power Query代替
- Codex×業務15選 部署別ガイド：営業/マーケ/人事/法務/経企/情シス/CSの15シーン
参考・出典
- OpenAI Agents SDK 公式ドキュメント — OpenAI（参照日: 2026-05-07）
- openai/openai-agents-python GitHub リポジトリ — OpenAI（参照日: 2026-05-07、v0.15.3、Stars 25.9k）
- Handoffs – OpenAI Agents SDK — OpenAI公式ドキュメント（参照日: 2026-05-07）
- Guardrails – OpenAI Agents SDK — OpenAI公式ドキュメント（参照日: 2026-05-07）
- Tracing – OpenAI Agents SDK — OpenAI公式ドキュメント（参照日: 2026-05-07）
- OpenAI Upgrades Its Agents SDK With Sandboxing and a New Model Harness — DevOps.com（2026年4月15日）
- GPT-5.5 Model — OpenAI API ドキュメント（参照日: 2026-05-07）
- OpenAI: GPT-5.5 – API Pricing — OpenRouter（参照日: 2026-05-07）
- GPT-5 does not work well compared to 4.1 — GitHub Issues（参照日: 2026-05-07）
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（旧Twitter）で活用法を発信（@SuguruKun_ai、フォロワー約10万人）。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
関連記事: MCP（Model Context Protocol）完全実装ガイド — Claude/Codex/Cursor統一プロトコルの実装ガイドです。
関連記事: AIエージェントセキュリティ完全ガイド｜OWASP対応 — AIエージェントのセキュリティ実装ガイドです。
