コンテンツにスキップ

クイックスタート

  1. プロジェクトを作成し、npm を初期化します。この操作は一度だけ行えば十分です。

    ターミナルウィンドウ
    mkdir my_project
    cd my_project
    npm init -y
  2. Agents SDK と Zod をインストールします。SDK はツールのスキーマと structured outputs に Zod v4 を使用します。

    ターミナルウィンドウ
    npm install @openai/agents zod
  3. OpenAI API キーを設定します。まだお持ちでない場合は、こちらの手順に従って OpenAI API キーを作成してください。

    ターミナルウィンドウ
    export OPENAI_API_KEY=sk-...

    または、setDefaultOpenAIKey('<api key>') を呼び出してプログラムでキーを設定し、トレーシングには setTracingExportApiKey('<api key>') を使用することもできます。詳しくは、SDK の設定をご覧ください。

はじめてのエージェントの作成

Section titled “はじめてのエージェントの作成”

エージェントは instructions と名前で定義します。

エージェントの作成
import { Agent } from '@openai/agents';
const agent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});

はじめてのエージェントの実行

Section titled “はじめてのエージェントの実行”

run メソッドを使用してエージェントを実行できます。実行を開始するエージェントと、渡したい入力の両方を指定すると、実行が開始されます。

最終出力と、その実行中に行われたアクションを含む実行結果が返されます。

エージェントの実行
import { Agent, run } from '@openai/agents';
const agent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});
const result = await run(agent, 'When did sharks first appear?');
console.log(result.finalOutput);

2 ターン目では、result.history を run() に再度渡すか、セッションを関連付けるか、conversationId / previousResponseId を使用して OpenAI のサーバーで管理される状態を再利用できます。エージェントの実行ガイドでは、これらの方法を比較しています。

エージェントへのツールの追加

Section titled “エージェントへのツールの追加”

エージェントにツールを与えると、情報の検索やアクションの実行に使用できます。

ツールの追加
import { Agent, tool } from '@openai/agents';
import { z } from 'zod';
const historyFunFact = tool({
// The name of the tool will be used by the agent to tell what tool to use.
name: 'history_fun_fact',
// The description is used to describe when to use the tool by telling it what it does.
description: 'Give a fun fact about a historical event',
// This tool takes no parameters, so we provide an empty Zod object.
parameters: z.object({}),
execute: async () => {
// The output will be returned back to the agent to use.
return 'Sharks are older than trees.';
},
});
const agent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
// Add the tool to the agent.
tools: [historyFunFact],
});

専門エージェントを追加で定義すると、問題をより小さな部分に分割し、各専門エージェントを 1 つのタスクに集中させ、問題に応じて異なるモデルを使用できます。

専門エージェントの作成
import { Agent } from '@openai/agents';
const historyTutorAgent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});
const mathTutorAgent = new Agent({
name: 'Math Tutor',
instructions:
'You provide help with math problems. Explain your reasoning at each step and include examples',
});

複数のエージェントをオーケストレーションするには、エージェントの handoffs を定義します。実行中にハンドオフが選択されると、ランナーは対象のエージェントに会話を自動的に引き継ぎます。

ハンドオフの定義
import { Agent } from '@openai/agents';
const historyTutorAgent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});
const mathTutorAgent = new Agent({
name: 'Math Tutor',
instructions:
'You provide help with math problems. Explain your reasoning at each step and include examples',
});
// Use Agent.create() to keep handoff output types aligned.
const triageAgent = Agent.create({
name: 'Triage Agent',
instructions:
"You determine which agent to use based on the user's homework question",
handoffs: [historyTutorAgent, mathTutorAgent],
});

実行後、実行結果の lastAgent プロパティを確認すると、どのエージェントが最終応答を生成したかがわかります。

エージェントオーケストレーションの実行

Section titled “エージェントオーケストレーションの実行”

ランナーは、個々のエージェントの実行、すべてのハンドオフ、すべてのツール呼び出しを処理します。

エージェントオーケストレーションの実行
import { Agent, run } from '@openai/agents';
const historyTutorAgent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});
const mathTutorAgent = new Agent({
name: 'Math Tutor',
instructions:
'You provide help with math problems. Explain your reasoning at each step and include examples',
});
const triageAgent = Agent.create({
name: 'Triage Agent',
instructions:
"You determine which agent to use based on the user's homework question",
handoffs: [historyTutorAgent, mathTutorAgent],
});
async function main() {
const result = await run(triageAgent, 'What is the capital of France?');
console.log(result.finalOutput);
}
main().catch((err) => console.error(err));

すべてを組み合わせたコード例

Section titled “すべてを組み合わせたコード例”

これまでの内容を 1 つの完全なコード例にまとめましょう。これを index.js ファイルに記述して実行してください。アプリがすでに TypeScript 用に設定されている場合は、代わりに index.ts を使用できます。

クイックスタート
import { Agent, run } from '@openai/agents';
const historyTutorAgent = new Agent({
name: 'History Tutor',
instructions:
'You provide assistance with historical queries. Explain important events and context clearly.',
});
const mathTutorAgent = new Agent({
name: 'Math Tutor',
instructions:
'You provide help with math problems. Explain your reasoning at each step and include examples',
});
const triageAgent = Agent.create({
name: 'Triage Agent',
instructions:
"You determine which agent to use based on the user's homework question",
handoffs: [historyTutorAgent, mathTutorAgent],
});
async function main() {
const result = await run(triageAgent, 'What is the capital of France?');
console.log(result.finalOutput);
}
main().catch((err) => console.error(err));

Agents SDK はトレースを自動的に生成します。これらのトレースを使用すると、エージェントがどのように動作しているか、どのツールを呼び出したか、どのエージェントがハンドオフを受け取ったかを確認できます。

エージェントの実行中に何が起きたかを確認するには、OpenAI ダッシュボードのトレースビューアーにアクセスしてください。

より複雑なエージェントのフローを構築する方法を学びましょう: