エージェント

エージェントは OpenAI Agents SDK の主要な構成要素です。Agent は、次の要素で設定された Large Language Model (LLM) です:

Instructions – モデルに 自分が何者か と どう応答すべきか を伝えるシステムプロンプト
Model – 呼び出す OpenAI モデルと、任意のモデル調整パラメーター
Tools – タスク達成のために LLM が呼び出せる関数や API のリスト

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

const agent = new Agent({
  name: 'Haiku Agent',
  instructions: 'Always respond in haiku form.',
  model: 'gpt-5.4', // optional – falls back to the default model
});

単一の Agent を定義またはカスタマイズしたいときはこのページを使ってください。複数のエージェントの協調方法を検討している場合は、エージェントオーケストレーションを参照してください。

次のガイドの選択

このページをエージェント定義のハブとして使ってください。次に必要な判断に合わせて、隣接するガイドへ進めます。

次のようなことをしたい場合	次に読むページ
モデルを選択する、または保存済みプロンプトを設定する	モデル
エージェントに機能を追加する	ツール
マネージャーとハンドオフのどちらを使うか決める	エージェントオーケストレーション
ハンドオフの挙動を設定する	ハンドオフ
ターン実行、イベントのストリーミング、状態管理を行う	エージェントの実行
最終出力、実行アイテムの確認、再開を行う	エージェントの実行結果

このページの残りでは、すべての Agent 機能をより詳しく説明します。

Agent の基本

基本設定

Agent コンストラクターは単一の設定オブジェクトを受け取ります。最もよく使われるプロパティは次のとおりです。

プロパティ	必須	説明
`name`	yes	人が読める短い識別子
`instructions`	yes	システムプロンプト（文字列 or 関数 - 動的 Instructions を参照）
`prompt`	no	OpenAI Responses API のプロンプト設定。静的なプロンプトオブジェクトまたは関数を受け取ります。Prompt を参照
`handoffDescription`	no	このエージェントをハンドオフツールとして提示する際に使う短い説明
`handoffs`	no	会話を専門エージェントへ委譲します。構成パターンとハンドオフガイドを参照
`model`	no	モデル名 or カスタム `Model` 実装
`modelSettings`	no	調整パラメーター（temperature、top_p など）。モデルを参照。必要なプロパティがトップレベルにない場合は `providerData` 配下に含められます
`tools`	no	モデルが呼び出せる `Tool` インスタンスの配列。ツールを参照
`mcpServers`	no	エージェント向けの MCP ベースツール。MCP 連携ガイドを参照
`inputGuardrails`	no	このエージェントチェーンの最初のユーザー入力に適用されるガードレール。ガードレールを参照
`outputGuardrails`	no	このエージェントの最終出力に適用されるガードレール。ガードレールを参照
`outputType`	no	プレーンテキストではなく構造化出力を返します。出力タイプとエージェントの実行結果を参照
`toolUseBehavior`	no	関数ツールの結果をモデルにループバックするか、実行を終了するかを制御します。ツール使用の強制を参照
`resetToolChoice`	no	ツール呼び出し後に `toolChoice` をデフォルトにリセットします（既定: `true`）。ツール使用ループの防止に役立ちます。ツール使用の強制を参照
`handoffOutputTypeWarningEnabled`	no	ハンドオフ間で出力タイプが異なる場合に警告を出します（既定: `true`）。エージェントの実行結果を参照

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

const getWeather = tool({
  name: 'get_weather',
  description: 'Return the weather for a given city.',
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: 'Weather bot',
  instructions: 'You are a helpful weather bot.',
  model: 'gpt-4.1',
  tools: [getWeather],
});

コンテキスト

エージェントは コンテキスト型に対してジェネリック です。つまり Agent<TContext, TOutput> です。コンテキスト は依存性注入オブジェクトで、作成して Runner.run() に渡します。これはすべてのツール、ガードレール、ハンドオフなどに渡され、状態保存や共有サービス（データベース接続、ユーザーメタデータ、機能フラグなど）の提供に役立ちます。

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

interface Purchase {
  id: string;
  uid: string;
  deliveryStatus: string;
}
interface UserContext {
  uid: string;
  isProUser: boolean;

  // this function can be used within tools
  fetchPurchases(): Promise<Purchase[]>;
}

const agent = new Agent<UserContext>({
  name: 'Personal shopper',
  instructions: 'Recommend products the user will love.',
});

// Later
import { run } from '@openai/agents';

const result = await run(agent, 'Find me a new pair of running shoes', {
  context: { uid: 'abc', isProUser: true, fetchPurchases: async () => [] },
});

出力タイプ

デフォルトでは Agent は プレーンテキスト（string）を返します。モデルに構造化オブジェクトを返させたい場合は、outputType プロパティを指定できます。SDK は次を受け付けます。

Zod スキーマ（z.object({...})）
JSON schema 互換の任意オブジェクト

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

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const extractor = new Agent({
  name: 'Calendar extractor',
  instructions: 'Extract calendar events from the supplied text.',
  outputType: CalendarEvent,
});

outputType が指定されると、SDK はプレーンテキストの代わりに自動的に structured outputs を使います。

OpenAI プラットフォームとの対応

一部のエージェント概念は OpenAI プラットフォームの概念に直接対応しますが、ほかはエージェント定義時ではなく実行時に設定します。

SDK 概念	OpenAI ガイド	重要になる場面
`outputType`	Structured Outputs	エージェントがテキストではなく、型付き JSON や Zod 検証済みオブジェクトを返す必要がある場合
`tools` / hosted tools	Tools guide	モデルで検索、取得、コード実行、または独自関数/ツール呼び出しを行う場合
`conversationId` / `previousResponseId`	Conversation state	ターン間の会話状態を OpenAI 側に永続化または連結したい場合

conversationId と previousResponseId は実行時の制御であり、Agent コンストラクターのフィールドではありません。これらの SDK エントリーポイントが必要な場合はエージェントの実行を使ってください。

構成パターン

エージェントがより大きなワークフローに参加する場合、よく使われる SDK エントリーポイントは 2 つです。

マネージャー（Agents as tools） - 中央エージェントが会話を管理し、ツールとして公開された専門エージェントを呼び出す
ハンドオフ - 最初のエージェントがユーザー要求を特定した後、会話全体を専門エージェントに委譲する

これらのアプローチは補完関係にあります。マネージャーはガードレールやレート制限を一元的に適用する場所を提供し、ハンドオフは会話制御を保持せずに各エージェントを単一タスクへ集中させます。設計上のトレードオフと選択指針はエージェントオーケストレーションを参照してください。

マネージャー（Agents as tools）

このパターンではマネージャーは制御を引き渡しません。LLM がツールを使い、最終回答はマネージャーが要約します。詳しくはツールガイドを参照してください。

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

const bookingAgent = new Agent({
  name: 'Booking expert',
  instructions: 'Answer booking questions and modify reservations.',
});

const refundAgent = new Agent({
  name: 'Refund expert',
  instructions: 'Help customers process refunds and credits.',
});

const customerFacingAgent = new Agent({
  name: 'Customer-facing agent',
  instructions:
    'Talk to the user directly. When they need booking or refund help, call the matching tool.',
  tools: [
    bookingAgent.asTool({
      toolName: 'booking_expert',
      toolDescription: 'Handles booking questions and requests.',
    }),
    refundAgent.asTool({
      toolName: 'refund_expert',
      toolDescription: 'Handles refund questions and requests.',
    }),
  ],
});

ハンドオフ

ハンドオフではトリアージエージェントがリクエストを振り分けますが、ハンドオフが発生すると専門エージェントが最終出力を生成するまで会話を担当します。これによりプロンプトを短く保て、各エージェントを独立して考えやすくなります。詳しくはハンドオフガイドを参照してください。

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

const bookingAgent = new Agent({
  name: 'Booking Agent',
  instructions: 'Help users with booking requests.',
});

const refundAgent = new Agent({
  name: 'Refund Agent',
  instructions: 'Process refund requests politely and efficiently.',
});

// Use Agent.create method to ensure the finalOutput type considers handoffs
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions: `Help the user with their questions.
  If the user asks about booking, hand off to the booking agent.
  If the user asks about refunds, hand off to the refund agent.`.trimStart(),
  handoffs: [bookingAgent, refundAgent],
});

ハンドオフ先が異なる出力タイプを返しうる場合は、new Agent(...) ではなく Agent.create(...) を推奨します。これにより TypeScript がハンドオフグラフ全体で可能な finalOutput 形状の union を推論でき、handoffOutputTypeWarningEnabled で制御される実行時警告も回避できます。エンドツーエンドの例はエージェントの実行結果ガイドを参照してください。

高度な設定と実行時制御

動的 Instructions

instructions には文字列ではなく関数を指定できます。この関数は現在の RunContext と Agent インスタンスを受け取り、文字列 または Promise<string> を返せます。

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

interface UserContext {
  name: string;
}

function buildInstructions(runContext: RunContext<UserContext>) {
  return `The user's name is ${runContext.context.name}. Be extra friendly!`;
}

const agent = new Agent<UserContext>({
  name: 'Personalized helper',
  instructions: buildInstructions,
});

同期関数と async 関数の両方をサポートします。

動的 Prompt

prompt は instructions と同じコールバック形式をサポートしますが、文字列ではなくプロンプト設定オブジェクトを返します。プロンプト ID、バージョン、変数が現在の実行コンテキストに依存する場合に有用です。

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

interface PromptContext {
  customerTier: 'free' | 'pro';
}

function buildPrompt(runContext: RunContext<PromptContext>) {
  return {
    promptId: 'pmpt_support_agent',
    version: '7',
    variables: {
      customer_tier: runContext.context.customerTier,
    },
  };
}

const agent = new Agent<PromptContext>({
  name: 'Prompt-backed helper',
  prompt: buildPrompt,
});

これは OpenAI Responses API を使う場合のみサポートされます。同期関数と async 関数の両方をサポートします。

ライフサイクルフック

高度なユースケースでは、イベントを監視して Agent のライフサイクルを観測できます。

Agent インスタンスはそのインスタンス固有のライフサイクルイベントを発行し、Runner は同じイベント名を実行全体の単一ストリームとして発行します。これは、ハンドオフやツール呼び出しを 1 か所で観測したいマルチエージェントワークフローで有用です。

共通のイベント名は次のとおりです。

Event	Agent hook arguments	Runner hook arguments
`agent_start`	`(context, agent, turnInput?)`	`(context, agent, turnInput?)`
`agent_end`	`(context, output)`	`(context, agent, output)`
`agent_handoff`	`(context, nextAgent)`	`(context, fromAgent, toAgent)`
`agent_tool_start`	`(context, tool, { toolCall })`	`(context, agent, tool, { toolCall })`
`agent_tool_end`	`(context, tool, result, { toolCall })`	`(context, agent, tool, result, { toolCall })`

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

const agent = new Agent({
  name: 'Verbose agent',
  instructions: 'Explain things thoroughly.',
});

agent.on('agent_start', (ctx, agent) => {
  console.log(`[${agent.name}] started`);
});
agent.on('agent_end', (ctx, output) => {
  console.log(`[agent] produced:`, output);
});

ガードレール

ガードレールを使うと、ユーザー入力やエージェント出力を検証または変換できます。inputGuardrails と outputGuardrails 配列で設定します。詳細はガードレールガイドを参照してください。

エージェントの複製 / コピー

既存エージェントを少し変更した版が必要ですか？clone() メソッドを使うと、まったく新しい Agent インスタンスを返します。

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

const pirateAgent = new Agent({
  name: 'Pirate',
  instructions: 'Respond like a pirate – lots of “Arrr!”',
  model: 'gpt-5.4',
});

const robotAgent = pirateAgent.clone({
  name: 'Robot',
  instructions: 'Respond like a robot – be precise and factual.',
});

ツール使用の強制

ツールを渡しても、LLM が必ず呼び出すとは限りません。modelSettings.toolChoice でツール使用を強制できます。

'auto'（デフォルト）- ツールを使うかどうかを LLM が決定
'required' - LLM はツール呼び出しが必須（どれを使うかは選択可能）
'none' - LLM はツールを呼び出してはならない
特定ツール名（例: 'calculator'）- LLM はそのツールを必ず呼び出す

利用可能なツールが OpenAI Responses の computerTool() の場合、toolChoice: 'computer' は特別です。'computer' を通常の関数名として扱うのではなく、GA の組み込みコンピュータツールを強制します。SDK は古い連携向けに preview 互換のコンピュータセレクターも受け付けますが、新規コードでは 'computer' を推奨します。コンピュータツールが利用できない場合、この文字列は他の関数ツール名と同様に振る舞います。

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

const calculatorTool = tool({
  name: 'Calculator',
  description: 'Use this tool to answer questions about math problems.',
  parameters: z.object({ question: z.string() }),
  execute: async (input) => {
    throw new Error('TODO: implement this');
  },
});

const agent = new Agent({
  name: 'Strict tool user',
  instructions: 'Always answer using the calculator tool.',
  tools: [calculatorTool],
  modelSettings: { toolChoice: 'required' },
});

toolNamespace() のような deferred Responses ツール、deferLoading: true の関数ツール、または deferLoading: true の hosted MCP ツールを使う場合は、modelSettings.toolChoice を 'auto' のままにしてください。これらの定義をいつ読み込むかはモデルが判断する必要があるため、SDK は deferred ツールや組み込み tool_search ヘルパーの名前指定による強制を拒否します。完全な tool-search の設定はツールガイドを参照してください。

無限ループの防止

ツール呼び出し後、SDK は自動的に toolChoice を 'auto' に戻します。これにより、モデルがツールを繰り返し呼ぼうとして無限ループに入るのを防ぎます。resetToolChoice フラグ、または toolUseBehavior の設定でこの挙動を上書きできます。

'run_llm_again'（デフォルト）- ツール結果を使って LLM を再実行
'stop_on_first_tool' - 最初のツール結果を最終回答として扱う
{ stopAtToolNames: ['my_tool'] } - 指定したいずれかのツールが呼ばれたら停止
(context, toolResults) => ... - 実行を終了すべきかを返すカスタム関数

const agent = new Agent({
  ...,
  toolUseBehavior: 'stop_on_first_tool',
});

注: toolUseBehavior が適用されるのは function tools のみです。Hosted tools は常に処理のためモデルに戻されます。