openai-agents

OpenAI Agents SDK スキル

OpenAI Agents SDK（JavaScript/TypeScript）を使用した AI アプリケーション構築のための包括的なスキルです。テキストエージェント、リアルタイム音声エージェント、マルチエージェントワークフロー、本番環境へのデプロイパターンを網羅しています。

---

クイックスタート

インストール

bun add @openai/agents zod@3
bun add @openai/agents-realtime  # For voice agents

環境変数を設定します：

export OPENAI_API_KEY="your-api-key"

基本的なテキストエージェント

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are helpful.',
  tools: [tool({
    name: 'get_weather',
    parameters: z.object({ city: z.string() }),
    execute: async ({ city }) => `Weather in ${city}: sunny`,
  })],
  model: 'gpt-4o-mini',
});

const result = await run(agent, 'What is the weather in SF?');

音声エージェントとマルチエージェント

// Voice agent
const voiceAgent = new RealtimeAgent({
  voice: 'alloy',
  model: 'gpt-4o-realtime-preview',
});

// Browser session
const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey, // From backend!
  transport: 'webrtc',
});

// Multi-agent handoffs
const triageAgent = Agent.create({
  handoffs: [billingAgent, techAgent],
});

17 個のテンプレート：templates/ ディレクトリには、すべてのパターンに対応した本番環境向けのサンプルがあります。

---

特に注意が必要なエラー 3 件

1. Zod スキーマの型エラー

エラー：構造的には互換性がある場合でも、ツールのパラメーターで型エラーが発生します。

回避策：スキーマをインラインで定義します。

// ❌ Can cause type errors
parameters: mySchema

// ✅ Works reliably
parameters: z.object({ field: z.string() })

出典：GitHub #188

2. MCP トレースエラー

エラー：MCP サーバーで「No existing trace found」が発生します。

回避策：

import { initializeTracing } from '@openai/agents/tracing';
await initializeTracing();

出典：GitHub #580

3. MaxTurnsExceededError

エラー：エージェントが無限ループします。

解決策：maxTurns を増やすか、指示を改善します：

const result = await run(agent, input, {
  maxTurns: 20,
});

// Or improve instructions
instructions: `After using tools, provide a final answer.
Do not loop endlessly.`

エラー全 9 件：回避策を含むエラー一覧については、references/common-errors.md を読み込んでください。

---

参照ファイルを読み込むタイミング

エージェント開発の特定の側面に取り組む際は、参照ファイルを読み込んでください：

エージェントのパターン（references/agent-patterns.md）

次の場合に読み込みます：

• マルチエージェントオーケストレーション戦略を設計する
• LLM ベースとコードベースのオーケストレーションから選択する
• エージェントの並列実行を実装する
• エージェントをツールとして使うパターンを作成する
• どのオーケストレーションパターンを使うべきか理解する必要がある

よくあるエラー（references/common-errors.md）

次の場合に読み込みます：

• 上記の特に注意が必要な 3 件以外のエージェントの問題をデバッグする
• 包括的なエラー処理を実装する
• GuardrailExecutionError、ToolCallError、Schema Mismatch、Ollama 統合、webSearchTool の失敗、Agent Builder のエクスポートの不具合に遭遇した
• 本番環境向けのエラー復旧パターンを構築する

リアルタイムトランスポート（references/realtime-transports.md）

次の場合に読み込みます：

• 音声エージェントに WebRTC と WebSocket のどちらを使うか選択する
• 音声エージェントのレイテンシーを最適化する
• 音声接続の問題をデバッグする
• 音声に必要なネットワークやファイアウォールの要件を理解する
• カスタム音声ソース／シンクを実装する

Cloudflare 統合（references/cloudflare-integration.md）

次の場合に読み込みます：

• エージェントを Cloudflare Workers にデプロイする
• Workers の制限（CPU、メモリ、音声非対応）を理解する
• Workers でストリーミングを実装する
• Workers 固有の問題をデバッグする
• Workers のパフォーマンスとコストを最適化する

公式リンク（references/official-links.md）

次の場合に読み込みます：

• 公式ドキュメントへのリンクが必要
• サンプルやコミュニティリソースを探す
• 最新の SDK バージョンを確認する
• 料金情報を探す
• 移行ガイドが必要

---

コアコンセプトの概要

エージェント：指示とツールを備えた LLM です。

ツール：エージェントが自動的に呼び出せる、Zod スキーマ付きの関数です。

ハンドオフ：エージェントがタスクを専門エージェントに振り分ける、マルチエージェントの委任です。

ガードレール：安全性を確保するための入出力検証（コンテンツフィルタリング、PII 検出）です。

構造化出力：Zod スキーマを使用した型安全な応答です。

ストリーミング：応答を段階的に返すリアルタイムのイベントストリーミングです。

Human-in-the-Loop：特定のツール実行に承認を必要とします（requiresApproval: true）。

詳しいサンプルについては、templates/text-agents/ と templates/realtime-agents/ のテンプレートを参照してください。

---

テキストエージェントのクイックリファレンス

// Basic
const result = await run(agent, 'Your question');

// Streaming
const stream = await run(agent, input, { stream: true });

// Structured output
const agent = new Agent({
  outputType: z.object({ sentiment: z.enum([...]), confidence: z.number() }),
});

テンプレート：templates/text-agents/（8 個のテンプレート）

---

リアルタイム音声エージェントのクイックリファレンス

const voiceAgent = new RealtimeAgent({
  voice: 'alloy', // alloy, echo, fable, onyx, nova, shimmer
  model: 'gpt-4o-realtime-preview',
});

const session = new RealtimeSession(voiceAgent, {
  apiKey: sessionApiKey,
  transport: 'webrtc', // or 'websocket'
});

音声ハンドオフの制約：ハンドオフ中に音声やモデルを変更することはできません。

テンプレート：templates/realtime-agents/（3 個のテンプレート） | 詳細：references/realtime-transports.md

---

フレームワーク統合のクイックリファレンス

Cloudflare Workers（実験的）

export default {
  async fetch(request: Request, env: Env) {
    const { message } = await request.json();
    process.env.OPENAI_API_KEY = env.OPENAI_API_KEY;

    const agent = new Agent({
      name: 'Assistant',
      instructions: 'Be helpful and concise',
      model: 'gpt-4o-mini',
    });

    const result = await run(agent, message, { maxTurns: 5 });

    return new Response(JSON.stringify({
      response: result.finalOutput,
      tokens: result.usage.totalTokens,
    }));
  },
};

制限事項：リアルタイム音声には対応していません。CPU 時間に制限があります（最大 30 秒）。メモリにも制約があります（128MB）。

テンプレート：templates/cloudflare-workers/（2 個のテンプレート）

詳細：Workers のガイド全体については、references/cloudflare-integration.md を読み込んでください。

Next.js App Router

// app/api/agent/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { Agent, run } from '@openai/agents';

export async function POST(request: NextRequest) {
  const { message } = await request.json();
  const agent = new Agent({ /* ... */ });
  const result = await run(agent, message);
  return NextResponse.json({ response: result.finalOutput });
}

テンプレート：templates/nextjs/（2 個のテンプレート）

---

ガードレールと人間の介入

// Input/output guardrails
const agent = new Agent({
  inputGuardrails: [homeworkDetectorGuardrail],
  outputGuardrails: [piiFilterGuardrail],
});

// Human approval
const tool = tool({
  requiresApproval: true,
  execute: async ({ amount }) => `Refunded $${amount}`,
});

// Handle approval loop
while (result.interruption?.type === 'tool_approval') {
  result = (await promptUser(result.interruption))
    ? await result.state.approve(result.interruption)
    : await result.state.reject(result.interruption);
}

テンプレート：templates/text-agents/agent-guardrails-*.ts、agent-human-approval.ts

---

オーケストレーションパターンの概要

LLM ベース：エージェントが自律的にルーティングを決定します。適応型ワークフローに使用します。

コードベース：制御フローを明示的に指定します。予測可能で決定論的なワークフローに使用します。

並列：複数のエージェントを同時に実行します。独立したタスクに使用します。

ツールとしてのエージェント：エージェントをツールとしてラップし、マネージャー LLM で利用します。専門的なタスクの委任に使用します。

詳細：包括的なオーケストレーション戦略と例については、references/agent-patterns.md を読み込んでください。

テンプレート：templates/text-agents/agent-parallel.ts

---

デバッグとトレーシング

process.env.DEBUG = '@openai/agents:*';

const result = await run(agent, input);
console.log('Tokens:', result.usage.totalTokens, 'Turns:', result.history.length);

テンプレート：templates/shared/tracing-setup.ts

---

本番環境チェックリスト

• OPENAI_API_KEY を環境シークレットとして設定する
• すべてのエージェント呼び出しにエラー処理を実装する
• 安全性が重要なアプリケーションにガードレールを追加する
• コストの予期しない増加を防ぐため、妥当な maxTurns を設定する
• 可能な場合は、コスト効率のために gpt-4o-mini を使用する
• レート制限を実装する
• コスト監視のためにトークン使用量を記録する
• ハンドオフのフローを十分にテストする
• API キーをブラウザーに決して公開しない（セッショントークンを使用する）
• デバッグのためにトレーシングと可観測性を有効にする

---

このスキルを使用する場面

✅ 使用する場合：

• マルチエージェントワークフローを構築するとき
• 音声 AI アプリケーションを作成するとき
• ツール呼び出しパターンを実装するとき
• 入出力の検証（ガードレール）が必要なとき
• 人間による承認ゲートが必要なとき
• 複雑な AI タスクをオーケストレーションするとき
• Cloudflare Workers または Next.js にデプロイするとき

❌ 使用しない場合：

• 単純な OpenAI API 呼び出し（代わりに openai-api スキルを使用してください）
• OpenAI 以外のモデルのみを使用するとき
• 大規模な本番音声処理（LiveKit Agents を検討してください）

---

トークン効率

推定削減率：約 60%

タスク	スキルなし	スキルあり	削減率
マルチエージェントのセットアップ	約 12k トークン	約 5k トークン	58%
音声エージェント	約 10k トークン	約 4k トークン	60%
エラーのデバッグ	約 8k トークン	約 3k トークン	63%
平均	約 10k	約 4k	約 60%

防止できるエラー：文書化された 9 件の問題に対し、エラーを 100% 防止

---

テンプレート一覧

テキストエージェント（8 個）：

1. agent-basic.ts - ツールを使うシンプルなエージェント
2. agent-handoffs.ts - マルチエージェントによるトリアージ
3. agent-structured-output.ts - Zod スキーマ
4. agent-streaming.ts - リアルタイムイベント
5. agent-guardrails-input.ts - 入力の検証
6. agent-guardrails-output.ts - 出力のフィルタリング
7. agent-human-approval.ts - HITL パターン
8. agent-parallel.ts - 並行実行

リアルタイムエージェント（3 個）： 9. realtime-agent-basic.ts - 音声のセットアップ 10. realtime-session-browser.tsx - React クライアント 11. realtime-handoffs.ts - 音声による委任

フレームワーク統合（4 個）： 12. worker-text-agent.ts - Cloudflare Workers 13. worker-agent-hono.ts - Hono フレームワーク 14. api-agent-route.ts - Next.js API 15. api-realtime-route.ts - Next.js 音声

ユーティリティ（2 個）： 16. error-handling.ts - 包括的なエラー処理 17. tracing-setup.ts - デバッグ

---

参考資料

1. agent-patterns.md - オーケストレーション戦略（LLM 対コード、並列、ツールとしてのエージェント）
2. common-errors.md - 回避策と出典を含む 9 件すべてのエラー
3. realtime-transports.md - WebRTC と WebSocket の比較、レイテンシー、デバッグ
4. cloudflare-integration.md - Workers のセットアップ、制限事項、パフォーマンス、コスト
5. official-links.md - ドキュメント、GitHub、npm、コミュニティリソース

---

Official Resources

• Docs: https://openai.github.io/openai-agents-js/
• GitHub: https://github.com/openai/openai-agents-js
• npm: https://www.npmjs.com/package/@openai/agents
• Issues: https://github.com/openai/openai-agents-js/issues

---

Version: SDK v0.3.3 Last Verified: 2025-11-21 Skill Author: Claude Skills Maintainers Production Tested: Yes