エージェントの実行

エージェントはそれ自体では何もしません – Runner クラスまたは run() ユーティリティで run します。

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});

const result = await run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

カスタムランナーが不要な場合は、シングルトンのデフォルト Runner インスタンスで実行する run() ユーティリティも使えます。

または、自分のランナーインスタンスを作成できます:

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant',
});

// You can pass custom configuration to the runner
const runner = new Runner();

const result = await runner.run(
  agent,
  'Write a haiku about recursion in programming.',
);
console.log(result.finalOutput);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

エージェントを実行すると、最終出力と実行全履歴を含むエージェントの実行結果オブジェクトを受け取ります。

エージェントループ

Runner の run メソッドでは、開始エージェントと入力を渡します。入力は文字列（ユーザーメッセージと見なされる）か、OpenAI Responses API のアイテムに相当する入力アイテムのリストのいずれかです。

ランナーは次のループを実行します:

現在の入力で現在のエージェントのモデルを呼び出す
LLM の応答を検査する
- Final output → 返す
- Handoff → 新しいエージェントへ切り替え、蓄積された会話履歴を保持して 1 に戻る
- Tool calls → ツールを実行し、その結果を会話に追加して 1 に戻る
maxTurns に達したら MaxTurnsExceededError をスローする

ランナーのライフサイクル

アプリ起動時に Runner を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシングなどのグローバル設定を保持します。まったく異なる構成が必要な場合のみ別の Runner を作成します。シンプルなスクリプトでは、内部でデフォルトランナーを使う run() を呼び出しても構いません。

実行引数

run() メソッドの入力は、実行を開始する初期エージェント、実行の入力、およびオプションのセットです。

入力は文字列（ユーザーメッセージと見なされる）、input items のリスト、または人間の介入（HITL）エージェントを構築する場合の RunState オブジェクトのいずれかです。

追加のオプションは次のとおりです:

Option	Default	Description
`stream`	`false`	`true` の場合、呼び出しは `StreamedRunResult` を返し、モデルから到着したイベントを逐次発行します
`context`	–	すべてのツール / ガードレール / ハンドオフに転送されるコンテキストオブジェクト。詳しくはコンテキスト管理を参照
`maxTurns`	`10`	セーフティ上限 – 到達時に `MaxTurnsExceededError` をスロー
`signal`	–	キャンセル用の `AbortSignal`
`session`	–	セッション永続化の実装。詳しくはセッションを参照
`sessionInputCallback`	–	セッション履歴と新規入力のカスタムマージロジック（モデル呼び出し前に実行）。詳しくはセッションを参照
`callModelInputFilter`	–	モデル呼び出し直前にモデル入力（items + 任意の instructions）を編集するフック。詳しくは Call model input filter を参照
`tracing`	–	実行ごとのトレーシング設定の上書き（例: エクスポート用 API キー）
`conversationId`	–	サーバー側の会話を再利用（OpenAI Responses API + Conversations API のみ）
`previousResponseId`	–	会話を作成せずに直前の Responses API 呼び出しから継続（OpenAI Responses API のみ）

ストリーミング

ストリーミングでは、LLM の実行に合わせてストリーミングイベントも受け取れます。ストリーム開始後、StreamedRunResult には新規出力を含む実行の完全な情報が含まれます。for await ループでストリーミングイベントを反復できます。詳しくはストリーミングを参照してください。

実行設定

独自の Runner インスタンスを作成する場合は、RunConfig オブジェクトでランナーを構成できます。

Field	Type	Purpose
`model`	`string \| Model`	実行中のすべてのエージェントに特定のモデルを強制適用
`modelProvider`	`ModelProvider`	モデル名を解決 – デフォルトは OpenAI プロバイダー
`modelSettings`	`ModelSettings`	エージェント個別設定を上書きするグローバルなチューニングパラメーター
`handoffInputFilter`	`HandoffInputFilter`	ハンドオフ時に入力アイテムを変更（ハンドオフ自体で未定義の場合）
`inputGuardrails`	`InputGuardrail[]`	最初のユーザー入力に適用されるガードレール
`outputGuardrails`	`OutputGuardrail[]`	最終出力に適用されるガードレール
`tracingDisabled`	`boolean`	OpenAI トレーシングを完全に無効化
`traceIncludeSensitiveData`	`boolean`	スパンは発行しつつ、トレースから LLM/ツールの入出力を除外
`workflowName`	`string`	Traces ダッシュボードに表示 – 関連する実行のグルーピングに役立つ
`traceId` / `groupId`	`string`	SDK に生成させず、手動で trace / group ID を指定
`traceMetadata`	`Record<string, string>`	すべてのスパンに付与する任意メタデータ
`tracing`	`TracingConfig`	実行ごとのトレーシング上書き（例: エクスポート用 API キー）
`sessionInputCallback`	`SessionInputCallback`	このランナー上のすべての実行に対するデフォルトの履歴マージ戦略
`callModelInputFilter`	`CallModelInputFilter`	各モデル呼び出し前にモデル入力を編集するグローバルフック

会話 / チャットスレッド

runner.run()（または run() ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の ターン を表します。エンドユーザーにどの程度の RunResult を見せるかは任意です（finalOutput のみ、または生成アイテムをすべてなど）。

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

let thread: AgentInputItem[] = [];

const agent = new Agent({
  name: 'Assistant',
});

async function userSays(text: string) {
  const result = await run(
    agent,
    thread.concat({ role: 'user', content: text }),
  );

  thread = result.history; // Carry over history + newly generated items
  return result.finalOutput;
}

await userSays('What city is the Golden Gate Bridge in?');
// -> "San Francisco"

await userSays('What state is it in?');
// -> "California"

インタラクティブ版はチャットのコード例を参照してください。

サーバー管理の会話

OpenAI Responses API に会話履歴を保持させ、毎ターンでローカル全文を送らないようにできます。長い会話や複数サービスの連携で有用です。詳細は Conversation state guide を参照してください。

OpenAI はサーバー側状態を再利用する 2 つの方法を提供します:

1. 会話全体に対する `conversationId`

Conversations API で一度会話を作成し、その ID を各ターンで再利用できます。SDK は新たに生成されたアイテムのみを自動的に含めます。

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply very concisely.',
});

async function main() {
  // Create a server-managed conversation:
  const client = new OpenAI();
  const { id: conversationId } = await client.conversations.create({});

  const first = await run(agent, 'What city is the Golden Gate Bridge in?', {
    conversationId,
  });
  console.log(first.finalOutput);
  // -> "San Francisco"

  const second = await run(agent, 'What state is it in?', { conversationId });
  console.log(second.finalOutput);
  // -> "California"
}

main().catch(console.error);

2. 直前のターンから継続するための `previousResponseId`

最初から Responses API のみで始めたい場合は、各リクエストを直前の応答が返す ID で連結できます。これにより、完全な会話リソースを作成せずにターン間でコンテキストを保持できます。

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

const agent = new Agent({
  name: 'Assistant',
  instructions: 'Reply very concisely.',
});

async function main() {
  const first = await run(agent, 'What city is the Golden Gate Bridge in?');
  console.log(first.finalOutput);
  // -> "San Francisco"

  const previousResponseId = first.lastResponseId;
  const second = await run(agent, 'What state is it in?', {
    previousResponseId,
  });
  console.log(second.finalOutput);
  // -> "California"
}

main().catch(console.error);

Call model input filter

モデルを呼び出す直前に callModelInputFilter でモデル入力を編集します。このフックは現在のエージェント、コンテキスト、（セッション履歴がある場合はそれも含めた）結合後の入力アイテムを受け取ります。機微情報の編集、古いメッセージの削除、追加の system 指示の注入などのために、更新した input 配列と任意の instructions を返してください。

runner.run(..., { callModelInputFilter }) で実行ごとに設定するか、Runner 構成（RunConfig の callModelInputFilter）でデフォルトとして設定します。

例外

SDK はキャッチ可能な小さなセットのエラーをスローします:

MaxTurnsExceededError – maxTurns に到達
ModelBehaviorError – モデルが不正な出力を生成（例: 不正な JSON、未知のツール）
InputGuardrailTripwireTriggered / OutputGuardrailTripwireTriggered – ガードレール違反
GuardrailExecutionError – ガードレールの実行失敗
ToolCallError – 関数ツールの呼び出しが失敗
UserError – 構成またはユーザー入力に基づくエラー

いずれも基底の AgentsError を拡張しており、現在の実行状態にアクセスするための state プロパティを提供する場合があります。

以下は GuardrailExecutionError を処理するサンプルコードです。入力ガードレールは最初のユーザー入力にのみ実行されるため、例では元の入力とコンテキストで実行を再開します。また、モデルを再呼び出しせずに出力ガードレールを再試行するために保存済み状態を再利用する方法も示します:

import {
  Agent,
  GuardrailExecutionError,
  InputGuardrail,
  InputGuardrailTripwireTriggered,
  OutputGuardrail,
  OutputGuardrailTripwireTriggered,
  run,
} from '@openai/agents';
import { z } from 'zod';

// Shared guardrail agent to avoid re-creating it on every fallback run.
const guardrailAgent = new Agent({
  name: 'Guardrail check',
  instructions: 'Check if the user is asking you to do their math homework.',
  outputType: z.object({
    isMathHomework: z.boolean(),
    reasoning: z.string(),
  }),
});

async function main() {
  const input = 'Hello, can you help me solve for x: 2x + 3 = 11?';
  const context = { customerId: '12345' };

  // Input guardrail example

  const unstableInputGuardrail: InputGuardrail = {
    name: 'Math Homework Guardrail (unstable)',
    execute: async () => {
      throw new Error('Something is wrong!');
    },
  };

  const fallbackInputGuardrail: InputGuardrail = {
    name: 'Math Homework Guardrail (fallback)',
    execute: async ({ input, context }) => {
      const result = await run(guardrailAgent, input, { context });
      const isMathHomework =
        result.finalOutput?.isMathHomework ??
        /solve for x|math homework/i.test(JSON.stringify(input));
      return {
        outputInfo: result.finalOutput,
        tripwireTriggered: isMathHomework,
      };
    },
  };

  const agent = new Agent({
    name: 'Customer support agent',
    instructions:
      'You are a customer support agent. You help customers with their questions.',
    inputGuardrails: [unstableInputGuardrail],
  });

  try {
    // Input guardrails only run on the first turn of a run, so retries must start a fresh run.
    await run(agent, input, { context });
  } catch (e) {
    if (e instanceof GuardrailExecutionError) {
      console.error(`Guardrail execution failed (input): ${e}`);
      try {
        agent.inputGuardrails = [fallbackInputGuardrail];
        // Retry from scratch with the original input and context.
        await run(agent, input, { context });
      } catch (ee) {
        if (ee instanceof InputGuardrailTripwireTriggered) {
          console.log('Math homework input guardrail tripped on retry');
        } else {
          throw ee;
        }
      }
    } else {
      throw e;
    }
  }

  // Output guardrail example

  const replyOutputSchema = z.object({ reply: z.string() });

  const unstableOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
    name: 'Answer review (unstable)',
    execute: async () => {
      throw new Error('Output guardrail crashed.');
    },
  };

  const fallbackOutputGuardrail: OutputGuardrail<typeof replyOutputSchema> = {
    name: 'Answer review (fallback)',
    execute: async ({ agentOutput }) => {
      const outputText =
        typeof agentOutput === 'string'
          ? agentOutput
          : (agentOutput?.reply ?? JSON.stringify(agentOutput));
      const flagged = /math homework|solve for x|x =/i.test(outputText);
      return {
        outputInfo: { flaggedOutput: outputText },
        tripwireTriggered: flagged,
      };
    },
  };

  const agent2 = new Agent<unknown, typeof replyOutputSchema>({
    name: 'Customer support agent (output check)',
    instructions: 'You are a customer support agent. Answer briefly.',
    outputType: replyOutputSchema,
    outputGuardrails: [unstableOutputGuardrail],
  });

  try {
    await run(agent2, input, { context });
  } catch (e) {
    if (e instanceof GuardrailExecutionError && e.state) {
      console.error(`Guardrail execution failed (output): ${e}`);
      try {
        agent2.outputGuardrails = [fallbackOutputGuardrail];
        // Output guardrails can be retried using the saved state without another model call.
        await run(agent2, e.state);
      } catch (ee) {
        if (ee instanceof OutputGuardrailTripwireTriggered) {
          console.log('Output guardrail tripped after retry with saved state');
        } else {
          throw ee;
        }
      }
    } else {
      throw e;
    }
  }
}

main().catch(console.error);

入力と出力の再試行の違い:

入力ガードレールは実行の最初のユーザー入力にのみ実行されるため、同じ入力/コンテキストで新規に実行を開始して再試行する必要があります。保存した state を渡しても入力ガードレールは再実行されません
出力ガードレールはモデル応答後に実行されるため、GuardrailExecutionError の保存済み state を再利用して、追加のモデル呼び出しなしに出力ガードレールのみを再実行できます

上記の例を実行すると、次の出力が表示されます:

Guardrail execution failed (input): Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework input guardrail tripped on retry
Guardrail execution failed (output): Error: Output guardrail failed to complete: Error: Output guardrail crashed.
Output guardrail tripped after retry with saved state

次のステップ

モデルの構成方法を学ぶ
エージェントにツールを提供する
本番運用に向けてガードレールやトレーシングを追加する