エージェント
エージェントは OpenAI Agents SDK の主要な構成要素です。Agent は、次の設定を持つ Large Language Model (LLM) です。
- Instructions – モデルに「自分が誰で」「どのように応答すべきか」を伝える system prompt
- 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-nano', // optional – falls back to the default model});このページの残りでは、すべての Agent 機能を詳しく説明します。
Agent コンストラクターは 1 つの設定オブジェクトを受け取ります。よく使用されるプロパティは以下のとおりです。
| Property | Required | Description |
|---|---|---|
name | yes | 短い人間可読の識別子 |
instructions | yes | System prompt(文字列 または 関数 – 動的 instructions を参照) |
model | no | モデル名 または カスタムの Model 実装 |
modelSettings | no | 調整用パラメーター(temperature、top_p など)。トップレベルにないプロパティが必要な場合は、providerData の下に含めることができます |
tools | no | モデルが呼び出せる Tool インスタンスの配列 |
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],});コンテキスト
Section titled “コンテキスト”エージェントはそのコンテキスト型に対してジェネリックです(例: 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.',});
// Laterimport { 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 を使用します。
マルチエージェントの設計パターン
Section titled “マルチエージェントの設計パターン”エージェントを組み合わせる方法は多数あります。プロダクションアプリでよく見られる 2 つのパターンは次のとおりです。
- マネージャー(エージェントをツールとして) – 会話を中央のエージェントが所有し、ツールとして公開された専門エージェントを呼び出します
- ハンドオフ – 初期エージェントがユーザーのリクエストを特定した後、会話全体を専門エージェントに委譲します
これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できるようにします。
マネージャー(エージェントをツールとして)
Section titled “マネージャー(エージェントをツールとして)”このパターンではマネージャーは制御を手放しません—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 handoffsconst 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],});動的 instructions
Section titled “動的 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 関数の両方がサポートされています。
ライフサイクルフック
Section titled “ライフサイクルフック”高度なユースケースでは、イベントをリッスンして Agent のライフサイクルを観測できます。利用可能な内容は、こちら に記載のエージェントフックのイベント名を参照してください。
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);});ガードレール
Section titled “ガードレール”ガードレールにより、ユーザー入力やエージェント出力の検証や変換ができます。inputGuardrails と outputGuardrails 配列で設定します。詳細は ガードレール を参照してください。
エージェントの複製/コピー
Section titled “エージェントの複製/コピー”既存のエージェントを少しだけ変更したバージョンが必要ですか?clone() メソッドを使うと、全く新しい Agent インスタンスが返されます。
import { Agent } from '@openai/agents';
const pirateAgent = new Agent({ name: 'Pirate', instructions: 'Respond like a pirate – lots of “Arrr!”', model: 'gpt-5-mini',});
const robotAgent = pirateAgent.clone({ name: 'Robot', instructions: 'Respond like a robot – be precise and factual.',});ツール使用の強制
Section titled “ツール使用の強制”ツールを提供しても、LLM が必ず呼び出すとは限りません。modelSettings.tool_choice でツール使用を強制できます。
'auto'(デフォルト)– ツールを使うかどうかを LLM が判断'required'– LLM はツールを呼び出す「必要がある」(どれを使うかは選べる)'none'– LLM はツールを呼び出してはならない- 特定のツール名(例:
'calculator')– LLM はその特定のツールを呼び出す必要がある
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: 'auto' },});無限ループの防止
Section titled “無限ループの防止”ツール呼び出し後、SDK は自動的に tool_choice を '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',});