クイックスタート

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

プロジェクトを作成し、npm を初期化します。これは一度だけ行えば十分です。
Terminal window
```
mkdir my_project
cd my_project
npm init -y
```
Agents SDK と Zod をインストールします。SDK は、ツールスキーマと structured outputs に Zod v4 を使用します。
Terminal window
```
npm install @openai/agents zod
```
OpenAI API キーを設定します。持っていない場合は、OpenAI API キーを作成するためにこちらの手順に従ってください。
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);

2 回目のターンでは、result.history を run() に渡し直すか、セッションをアタッチするか、conversationId / previousResponseId を使って OpenAI サーバー管理の状態を再利用できます。エージェントの実行ガイドでは、これらのアプローチを比較しています。

エージェントへのツールの付与

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

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],
});

追加エージェントの作成

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

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 プロパティを見ると、どのエージェントが最終レスポンスを生成したかを確認できます。

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

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

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

すべての統合

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 Dashboard のトレースビューアーに移動してください。

次のステップ

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

エージェントの設定について学びます。
エージェントの実行とセッションについて学びます。
ツール、ガードレール、モデルについて学びます。