OpenAI Agents SDK TS比較｜Python版との違い

結論から言うと、OpenAI Agents SDK TypeScript版は「WebアプリやNode.jsの業務システムにAIエージェントを組み込む」用途で選びやすいSDKです。Python版はデータ処理や検証スクリプトに強く、TypeScript版はフロントエンド連携、型安全な業務アプリ、Realtime UIとの接続で扱いやすい。この記事では、2026年5月23日時点で確認できる公式ドキュメントとパッケージ情報をもとに、どちらを選ぶべきかを実装目線で整理します。

OpenAI Agents SDK TypeScript版とは

OpenAI Agents SDK TypeScriptは、OpenAIが公開しているAIエージェント構築用SDKです。公式ドキュメントでは、軽量ながら複数エージェントのワークフローを組めるフレームワークとして説明されています。npmの公開パッケージは@openai/agentsで、2026年5月23日の確認時点ではlatestが0.11.5でした。

基本の作りはシンプルです。Agentで役割と指示を定義し、run()で入力を渡します。ここにTools、Handoffs、Tracingを足していくと、単なるチャットボットではなく「調べる・判断する・別担当へ渡す・実行ログを追う」業務フローに近づきます。

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Support Triage',
  instructions: '問い合わせを分類し、次の対応方針を短く返す。',
});

const result = await run(agent, '請求書の宛名を変更したいです');
console.log(result.finalOutput);

AIgent Labでは、エージェント設計の基礎としてAIエージェントのプロンプト設計術も整理しています。今回のSDK比較は、その設計を実際のアプリに落とすための実装編として読むとつながりやすいです。

TypeScript版とPython版の違い

Python版の公式ドキュメントはOpenAI Agents SDK for Pythonとして公開されています。PyPIのopenai-agentsは、2026年5月23日の確認時点で0.17.3がlatestでした。バージョン番号だけで優劣は判断できません。見るべきは「どの実行環境に近いか」です。

観点	TypeScript版	Python版
得意な場所	Node.js、Next.js、Web API、ブラウザ連携	Pythonバッチ、データ処理、検証スクリプト
導入単位	npm install @openai/agents zod	pip install openai-agents
型の扱い	TypeScriptの型とZodでUI/APIに寄せやすい	PydanticやPython型ヒントと相性がよい
チーム適性	Web開発チーム、SaaS開発チーム	ML/データ分析チーム、PoCチーム
運用観点	既存のNodeログ、APIルート、フロントの状態管理に寄せやすい	ノートブック、ETL、評価ジョブとつなぎやすい

たとえば、問い合わせ管理SaaSにAIエージェントを組み込むならTypeScript版が自然です。一方、社内文書を一括評価してナレッジベースを作るようなバッチ処理ならPython版が書きやすい。重要なのは、モデル性能ではなく周辺システムとの距離です。

最小構成：5分で動かす実装

TypeScript版の公式Quickstartでは、@openai/agentsとzodをインストールして、最初のAgentを作る流れが紹介されています。環境変数にAPIキーを設定したうえで、Node.js/TypeScriptのプロジェクトから実行します。

npm install @openai/agents zod
export OPENAI_API_KEY="sk-..."

import { Agent, run } from '@openai/agents';

const historyTutor = new Agent({
  name: 'History Tutor',
  instructions: '歴史上の出来事を、背景と影響に分けて説明する。',
});

const result = await run(historyTutor, 'サメはいつ頃から存在している？');
console.log(result.finalOutput);

ここで注意したいのは、最初から複雑なツール実行を入れないことです。まず「単一Agentで、入力に対して期待した粒度で返せるか」を確認します。その後にToolsやHandoffsを足した方が、失敗時の切り分けが楽です。これはAIエージェントのハルシネーション対策でも重要になる考え方です。

Tools：外部処理を安全に足す

Agents SDKの実運用で差が出るのはToolsです。公式のToolsガイドでは、Hosted tools、Built-in execution tools、Function tools、Agents as tools、MCP serversなど複数のカテゴリが整理されています。つまり「何でも自由に実行させる」のではなく、用途ごとに道具を分ける設計が前提です。

業務アプリでは、まずFunction toolから始めるのが安全です。たとえば問い合わせ種別をCRMへ登録する、商品IDから在庫を引く、といった限定的な処理だけを公開します。

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

const lookupOrder = tool({
  name: 'lookup_order',
  description: '注文IDから配送状況を取得する',
  parameters: z.object({ orderId: z.string() }),
  execute: async ({ orderId }) => {
    // 実運用ではDBや社内APIを呼ぶ
    return { orderId, status: '発送準備中' };
  },
});

const agent = new Agent({
  name: 'Order Support',
  instructions: '注文問い合わせに回答する。必要な場合だけ注文検索ツールを使う。',
  tools: [lookupOrder],
});

const result = await run(agent, '注文A-123の状況を教えて');
console.log(result.finalOutput);

Toolsを増やすほど便利になりますが、同時に誤実行リスクも増えます。書き込み系ツール、決済系ツール、外部送信ツールは、ユーザー確認や権限チェックを別レイヤーで置くべきです。SDKに任せる部分と、アプリ側で守る部分を分けるのが実装のコツです。

Handoffs：担当エージェントを分ける

複数部署の問い合わせを1つのAgentに詰め込むと、指示が長くなり、挙動も読みにくくなります。そこで使うのがHandoffsです。公式のHandoffsガイドでは、Triage agentからBilling agentやRefund agentへ渡す例が示されています。

import { Agent, handoff } from '@openai/agents';

const billingAgent = new Agent({
  name: 'Billing agent',
  instructions: '請求・領収書・支払い方法の問い合わせだけを扱う。',
});

const refundAgent = new Agent({
  name: 'Refund agent',
  instructions: '返金条件と返金手続きの問い合わせだけを扱う。',
});

const triageAgent = Agent.create({
  name: 'Triage agent',
  instructions: '問い合わせ内容を読み、適切な担当へ渡す。',
  handoffs: [billingAgent, handoff(refundAgent)],
});

Handoffsを使うと、各Agentの責務を短く保てます。個人的には、最初から10体のAgentを作るより、Triage、Task、Reviewの3役くらいから始めるのが現実的です。権限の強い処理はReview側に寄せる、顧客対応文面はTask側で作る、という分け方にすると監査もしやすくなります。

Tracing：本番運用で必ず見るべきログ

エージェントは「なぜそのツールを呼んだのか」「どこで別Agentに渡したのか」が見えないと、運用で詰まります。公式のTracingガイドでは、TraceとSpan、デフォルトトレーシング、カスタムTraceの作り方が説明されています。

Web APIやCloudflare Workersのような環境では、リクエスト終了時にtrace providerをflushする実装例も示されています。ここは地味ですが、本番ではかなり大事です。ログが欠けると、ユーザーから「変な返答をした」と言われた時に再現できません。

import { Agent, run, withTrace } from '@openai/agents';

const agent = new Agent({
  name: 'Joke reviewer',
  instructions: '短いジョークを作り、次に自己評価する。',
});

await withTrace('demo workflow', async () => {
  const first = await run(agent, 'エンジニア向けの短いジョークを作って');
  const second = await run(agent, `このジョークを10点満点で評価して: ${first.finalOutput}`);
  console.log(first.finalOutput);
  console.log(second.finalOutput);
});

本番導入では、Trace ID、ユーザーID、ツール名、実行結果、エラー理由をアプリ側のログにも残すと安全です。ただし、個人情報や機密情報をそのままTraceに入れない設計が必要です。ログは多ければよいのではなく、あとから原因追跡できる粒度で、漏れてはいけない情報を落として保存します。

選び方：TS版を選ぶべきケース

TypeScript版を選ぶべきなのは、AIエージェントをユーザー体験の中に組み込むケースです。たとえば、管理画面のサイドバーでAIが顧客情報を読み取り、必要なら社内APIを呼び、担当者向けに次アクションを出すような実装です。UI、API、認証、ログが同じTypeScript/Node.js圏内にあるなら、SDKも同じ言語に寄せた方が開発速度が上がります。

逆に、評価データセットを回す、数千件の文書を分類する、RAGの前処理を試す、といった用途ではPython版が自然です。すでにPythonで評価パイプラインがあるなら、無理にTypeScriptへ寄せる必要はありません。判断基準は「エージェントが最終的にどこで動くか」です。

• Webアプリ内のAI機能として出すならTypeScript版
• 社内APIやSaaS管理画面に組み込むならTypeScript版
• データ分析、評価、バッチ処理が中心ならPython版
• PoCはPython、本番UIはTypeScriptという分担もあり

失敗パターンと実装チェックリスト

Agents SDKを触り始める時に多い失敗は、最初から「全部できる秘書」を作ろうとすることです。結果としてToolsが増えすぎ、Handoffsの条件が曖昧になり、Tracingを見ても何が起きたのか分からなくなります。

最初の1週間は、次のチェックリストだけで十分です。

1. Agentの責務を1文で説明できるか
2. Toolsは読み取り系から始めているか
3. 書き込み系Toolsに確認ステップを置いているか
4. Handoffsの条件をユーザーにも説明できるか
5. Traceでツール呼び出しと最終回答を追えるか
6. 失敗時に人間へ戻す導線があるか

この6つを満たしてから、MCP連携やRealtime UIに広げる方が堅いです。派手なデモより、失敗した時に止められる設計の方が、実務では価値があります。

関連記事・次に読む

SDKを選ぶ前に、まずプロンプトと責務分離を固めたい場合はAIエージェントのプロンプト設計術をどうぞ。運用時の幻覚・誤実行が不安な場合はハルシネーション対策7選を先に読むと、Tools設計の落とし穴が見えます。さらに可観測性まで含めて考えるなら、LangSmith完全ガイドも参考になります。

まとめ：本番に近い言語で選ぶ

OpenAI Agents SDKのTypeScript版とPython版は、どちらが上というより、置き場所が違います。Webアプリ、SaaS、管理画面、Node.js APIに近いならTypeScript版。検証、評価、データ処理に近いならPython版。まずは単一Agent、読み取りTools、Tracingありの小さな構成で始めるのがおすすめです。

SDK選定で迷ったら、「モデルに何をさせたいか」より先に「失敗した時に誰が止めるか」を決めてください。そこが決まると、Toolsの権限、Handoffsの分岐、ログの持ち方が自然に決まります。