エージェント

エージェントは、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: 'o4-mini', // optional – falls back to the default model
});

このページでは、エージェントのすべての機能を順に詳しく説明します。

基本設定

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

Property	Required	説明
`name`	yes	短い人間が読みやすい識別子
`instructions`	yes	システムプロンプト（文字列または関数。詳細は Dynamic instructions を参照）
`model`	no	モデル名またはカスタム `Model` 実装
`modelSettings`	no	temperature、top_p などのチューニングパラメーター
`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: 'o4-mini',
  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 () => [] },
});

出力型

デフォルトでは、エージェントは プレーンテキスト（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 を自動的に使用します。

ハンドオフ

エージェントは handoffs プロパティを介して他のエージェントへ委譲できます。よくあるパターンとして、会話をより専門的なサブエージェントに振り分ける トリアージエージェント を使用します。

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.',
  ].join('\n'),
  handoffs: [bookingAgent, refundAgent],
});

このパターンの詳細はハンドオフガイドをご覧ください。

Dynamic 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 関数のどちらもサポートされています。

ライフサイクルフック

高度なユースケースでは、イベントをリッスンしてエージェントのライフサイクルを監視できます。

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: 'o4-mini',
});

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

ツール使用の強制

ツールを提供しても、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' },
});

無限ループの防止

ツール呼び出し後、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',
});

次のステップ

エージェントの実行を学ぶ
ツール、ガードレール、モデルを詳しく見る
サイドバーの @openai/agents にある完全な TypeDoc リファレンスを参照する