クイックスタート

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

プロジェクトを作成して npm を初期化します。一度だけ実行すれば大丈夫です
Terminal window
```
mkdir my_project
cd my_project
npm init -y
```
Agents SDK をインストールします
Terminal window
```
npm install @openai/agents zod@3
```
OpenAI API key を設定します。まだお持ちでない場合は、OpenAI API key の作成手順はこちらの手順をご覧ください
Terminal window
```
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 メソッドでエージェントを実行できます。開始したいエージェントと、それに渡したい入力の両方を渡して実行します。

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

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 viewerに移動します。

次のステップ

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

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