快速开始

项目设置

创建项目并初始化 npm。此操作只需执行一次。
Terminal window
```
mkdir my_project
cd my_project
npm init -y
```
安装 Agents SDK 和 Zod。SDK 使用 Zod v4 定义工具 schema 和 structured outputs。
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);

对于第二轮交互，您可以将 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],
});

交接的定义

要编排多个智能体，请定义智能体的 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));

完整示例

下面将所有内容整合为一个完整示例。请将其放入 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 控制面板中的追踪查看器。

后续步骤

了解如何构建更复杂的智能体工作流：

了解如何配置智能体。
了解运行智能体和会话。
了解工具、护栏和模型。