For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

エージェントの定義

ワークフローを拡張する前に、まずは 1 つのエージェントの役割を明確にして設定します。

エージェントは、SDK で構築するワークフローの基本単位です。モデルと指示をまとめ、必要に応じてツール、ガードレール、MCP サーバー、ハンドオフ、構造化出力などの実行時機能を組み込めます。

エージェントの設定項目

各エージェントの役割に固有の設定は、エージェント自体に定義します。

プロパティ 用途 関連ガイド
name トレース、ツール、ハンドオフでエージェントを識別するための読みやすい名前 このページ
instructions エージェントの役割、制約、応答スタイルの指定 このページ
prompt Responses API を使った実行で参照する保存済みプロンプト設定の指定 モデルとプロバイダー
model とモデル設定 モデルの選択と動作の調整 モデルとプロバイダー
tools エージェントが直接呼び出せる機能の指定 ツールの使い方
handoffDescription 他のエージェントがこのエージェントに処理を委任する際の判断基準の提示 オーケストレーションとハンドオフ
handoffs 他のエージェントへの処理の委任 オーケストレーションとハンドオフ
outputType プレーンテキストの代わりに構造化出力を返すための設定 このページ
ガードレールと承認 検証、ブロック、レビューのフローの設定 ガードレールと人によるレビュー
MCP サーバーとホスト型 MCP ツール MCP 経由で利用できる機能の追加 外部連携とオブザーバビリティ

役割を絞ったエージェントの定義

まず、明確なタスクを担当できる最小構成のエージェントを定義します。エージェントを追加するのは、担当を分ける必要がある場合や、役割ごとに指示、利用できるツール、承認ポリシーを変える必要がある場合だけです。

単一のエージェントの定義
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-6-astra",
  tools: [getWeather],
});

指示、ハンドオフ、出力の設定

次の 3 つの設定には特に注意してください。

  • まずは静的な instructions を使います。現在のユーザー、テナント、実行時のコンテキストに応じて指示を変える必要がある場合は、呼び出し側で文字列をつなぎ合わせず、指示を動的に生成するコールバックに切り替えます。
  • handoffDescription は短く具体的に記述します。そうすると、振り分けを担当するエージェントが、どのような場合にこの専門エージェントを選べばよいか判断できます。
  • 後続のコードが自由形式の文章ではなく型付きデータを必要とする場合は、outputType を使います。
構造化出力の返し方
import { Agent, run } from "@openai/agents";
import { z } from "zod";

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

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

システムプロンプト全体をコードに埋め込まずに、Responses API から保存済みのプロンプト設定を参照するには、prompt を使います。

ローカルコンテキストとモデルのコンテキストの区別

SDK では、アプリケーションの状態や依存オブジェクトをモデルに送信せずに、エージェントの実行時に渡せます。認証済みユーザーの情報、データベースクライアント、ロガー、ヘルパー関数などを渡すときに使います。

ツールへのローカルコンテキストの受け渡し
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  // TypeScript users can type this as RunContext<{ name: string; uid: number }>.
  async execute(_args, runContext) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

両者の違いは、誰がその情報を参照できるかにあります。

  • 会話履歴は、モデルが参照する情報です。
  • 実行コンテキストは、アプリケーションのコードが参照する情報です。

モデルが必要とする情報は、指示や入力に含めるか、検索やツールを通じて提供します。実行環境だけが必要とする情報は、ローカルコンテキストに保持します。

エージェントを分割する判断基準

1 つの専門エージェントに応答全体を任せるのが適切でない場合や、担当する機能に大きな違いがある場合は、エージェントを分割します。典型的な理由は次のとおりです。

  • 専門エージェントごとに異なるツールや MCP インターフェースが必要な場合
  • 専門エージェントごとに異なる承認ポリシーやガードレールが必要な場合
  • ワークフローの特定の分岐で異なるモデルや出力スタイルが必要な場合
  • 1 つの大きなプロンプトに処理をまとめず、どのエージェントに振り分けたかをトレースで明示したい場合

次のステップ

1 つの専門エージェントの役割と設定が明確になったら、次に検討したい設計項目に合うガイドに進んでください。