モデル

すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースで抽象化しています。

Model – 特定 API へ 1 回 のリクエストを行う方法を知っています
ModelProvider – 人が読みやすいモデル名（例: 'gpt-4o'）を Model インスタンスへ解決します

普段の開発では通常、モデル名と、ときどき ModelSettings のみを扱います。

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

const agent = new Agent({
  name: 'Creative writer',
  model: 'gpt-4.1',
});

OpenAI プロバイダー

デフォルトの ModelProvider は OpenAI API を使ってモデル名を解決します。次の 2 つのエンドポイントをサポートします。

API	用途	`setOpenAIAPI()` の呼び出し
Chat Completions	標準のチャット & 関数呼び出し	`setOpenAIAPI('chat_completions')`
Responses	ストリーミング優先の新しい生成 API（ツール呼び出し、柔軟な出力）	`setOpenAIAPI('responses')` (デフォルト)

認証

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

setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

ネットワーク設定をカスタマイズしたい場合は、setDefaultOpenAIClient(client) で独自の OpenAI クライアントを差し替えることもできます。

デフォルトモデル

OpenAI プロバイダーのデフォルトは gpt-4o です。エージェント単位またはグローバルに上書きできます。

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

const runner = new Runner({ model: 'gpt‑4.1-mini' });

ModelSettings

ModelSettings は OpenAI のパラメーターを反映しつつ、プロバイダーに依存しません。

フィールド	型	説明
`temperature`	`number`	創造性と決定論のバランス
`topP`	`number`	ニュークリアスサンプリング
`frequencyPenalty`	`number`	繰り返しトークンのペナルティ
`presencePenalty`	`number`	新しいトークンを促進
`toolChoice`	`'auto' \| 'required' \| 'none' \| string`	ツール使用の強制を参照
`parallelToolCalls`	`boolean`	対応している場合に関数呼び出しを並列化
`truncation`	`'auto' \| 'disabled'`	トークン切り捨て戦略
`maxTokens`	`number`	返信の最大トークン数
`store`	`boolean`	レスポンスを保存し、取得 / RAG ワークフローで再利用

設定はどちらのレベルにも付与できます。

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

const agent = new Agent({
  name: 'Creative writer',
  // ...
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});

// or globally
new Runner({ modelSettings: { temperature: 0.3 } });

Runner レベルの設定は、エージェント個別設定と競合した場合に優先されます。

Prompt

エージェントには prompt パラメーターを設定できます。これはサーバーに保存されたプロンプト設定を利用してエージェントの挙動を制御するものです。現在、このオプションは OpenAI の Responses API を使用する場合にのみ対応しています。

フィールド	型	説明
`promptId`	`string`	プロンプトの一意な識別子
`version`	`string`	利用したいプロンプトのバージョン
`variables`	`object`	プロンプトに代入するキー／値のペア。値には文字列やテキスト、画像、ファイルなどのコンテンツ入力型を指定できます

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

async function main() {
  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId: 'pmpt_684b3b772e648193b92404d7d0101d8a07f7a7903e519946',
      version: '1',
      variables: {
        poem_style: 'limerick',
      },
    },
  });

  const result = await run(agent, 'Write about unrequited love.');
  console.log(result.finalOutput);
}

if (require.main === module) {
  main().catch(console.error);
}

ツールや instructions など、追加のエージェント設定を行うと、保存済みプロンプトの値を上書きします。

カスタムモデルプロバイダー

独自プロバイダーの実装は簡単です。ModelProvider と Model を実装し、Runner コンストラクターに渡すだけです。

import {
  ModelProvider,
  Model,
  ModelRequest,
  ModelResponse,
  ResponseStreamEvent,
} from '@openai/agents-core';

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

class EchoModel implements Model {
  name: string;
  constructor() {
    this.name = 'Echo';
  }
  async getResponse(request: ModelRequest): Promise<ModelResponse> {
    return {
      usage: {},
      output: [{ role: 'assistant', content: request.input as string }],
    } as any;
  }
  async *getStreamedResponse(
    _request: ModelRequest,
  ): AsyncIterable<ResponseStreamEvent> {
    yield {
      type: 'response.completed',
      response: { output: [], usage: {} },
    } as any;
  }
}

class EchoProvider implements ModelProvider {
  getModel(_modelName?: string): Promise<Model> | Model {
    return new EchoModel();
  }
}

const runner = new Runner({ modelProvider: new EchoProvider() });
console.log(runner.config.modelProvider.getModel());
const agent = new Agent({
  name: 'Test Agent',
  instructions: 'You are a helpful assistant.',
  model: new EchoModel(),
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});
console.log(agent.model);

トレーシングエクスポーター

OpenAI プロバイダー使用時に、API キーを指定すると自動トレースエクスポートを有効化できます。

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

setTracingExportApiKey('sk-...');

これによりトレースが OpenAI ダッシュボードへ送信され、ワークフローの完全な実行グラフを確認できます。

次のステップ

エージェントの実行を試してみましょう
ツールでモデルを強化しましょう
必要に応じてガードレールやトレーシングを追加しましょう