エージェントは、SDK で構築するワークフローの基本単位です。モデルと指示をまとめ、必要に応じてツール、ガードレール、MCP サーバー、ハンドオフ、構造化出力などの実行時機能を組み込めます。
エージェントの設定項目
各エージェントの役割に固有の設定は、エージェント自体に定義します。
| プロパティ | 用途 | 関連ガイド |
|---|---|---|
name |
トレース、ツール、ハンドオフでエージェントを識別するための読みやすい名前 | このページ |
instructions |
エージェントの役割、制約、応答スタイルの指定 | このページ |
prompt |
Responses API を使った実行で参照する保存済みプロンプト設定の指定 | モデルとプロバイダー |
model とモデル設定 |
モデルの選択と動作の調整 | モデルとプロバイダー |
tools |
エージェントが直接呼び出せる機能の指定 | ツールの使い方 |
handoffDescription |
他のエージェントがこのエージェントに処理を委任する際の判断基準の提示 | オーケストレーションとハンドオフ |
handoffs |
他のエージェントへの処理の委任 | オーケストレーションとハンドオフ |
outputType |
プレーンテキストの代わりに構造化出力を返すための設定 | このページ |
| ガードレールと承認 | 検証、ブロック、レビューのフローの設定 | ガードレールと人によるレビュー |
| MCP サーバーとホスト型 MCP ツール | MCP 経由で利用できる機能の追加 | 外部連携とオブザーバビリティ |
役割を絞ったエージェントの定義
まず、明確なタスクを担当できる最小構成のエージェントを定義します。エージェントを追加するのは、担当を分ける必要がある場合や、役割ごとに指示、利用できるツール、承認ポリシーを変える必要がある場合だけです。
単一のエージェントの定義
JavaScript
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
構造化出力の返し方
JavaScript
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 では、アプリケーションの状態や依存オブジェクトをモデルに送信せずに、エージェントの実行時に渡せます。認証済みユーザーの情報、データベースクライアント、ロガー、ヘルパー関数などを渡すときに使います。
ツールへのローカルコンテキストの受け渡し
JavaScript
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 つの専門エージェントの役割と設定が明確になったら、次に検討したい設計項目に合うガイドに進んでください。