クイックスタート

プロジェクトのセットアップ

1. プロジェクトを作成して npm を初期化します。これは最初の一度だけで大丈夫です。

   mkdir my_project
   cd my_project
   npm init -y

2. Agents SDK をインストールします。

   npm install @openai/agents 'zod@<=3.25.67'

3. OpenAI API キーを設定します。まだお持ちでない場合は、こちらの手順 に従って OpenAI API キーを作成してください。

   export OPENAI_API_KEY=sk-...

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

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

エージェントは 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.',
});

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

run メソッドを使ってエージェントを実行できます。実行を開始するには、開始したいエージェントと渡したい入力の両方を渡します。

これにより、その実行中に行われた最終出力とすべてのアクションを含む result が返されます。

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);

エージェントにツールを持たせる

エージェントにツールを与えて、情報を検索したりアクションを実行したりさせることができます。

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

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.',
  // Adding the tool to the agent
  tools: [historyFunFact],
});

さらにエージェントを追加する

追加のエージェントを同様に定義して、問題をより小さな部分に分割し、タスクに集中させることができます。また、エージェントごとにモデルを定義することで、異なる問題に異なるモデルを使用できます。

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 を定義できます。これにより、実行中に会話が自動的に次のエージェントへ引き継がれます。

// Using the Agent.create method to ensures type safety for the final output
const triageAgent = Agent.create({
  name: 'Triage Agent',
  instructions:
    "You determine which agent to use based on the user's homework question",
  handoffs: [historyTutorAgent, mathTutorAgent],
});

実行後、finalAgent プロパティを見ることで、最終的な応答を生成したエージェントを確認できます。

エージェントオーケストレーションを実行する

Runner は個々のエージェントの実行、ハンドオフの可能性、ツールの実行を管理します。

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

async function main() {
  const result = await run(triageAgent, 'What is the capital of France?');
  console.log(result.finalOutput);
}

main().catch((err) => console.error(err));

すべてをまとめる

これまでの内容を 1 つの例にまとめましょう。index.js に配置して実行してください。

クイックスタート

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 = new Agent({
  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 ダッシュボードの Trace ビューア に移動してください。

次のステップ

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

• エージェント の設定方法を学ぶ
• エージェントの実行 について学ぶ
• ツール、ガードレール、モデル について学ぶ