@openai/agents 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# OpenAI Agents SDK (JavaScript/TypeScript)
+
+The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows in JavaScript/TypeScript. It is provider-agnostic, supporting OpenAI APIs and more.
+
+<img src="https://cdn.openai.com/API/docs/images/orchestration.png" alt="Image of the Agents Tracing UI" style="max-height: 803px;">
+
+## Core concepts
+
+1. **Agents**: LLMs configured with instructions, tools, guardrails, and handoffs.
+2. **Handoffs**: Specialized tool calls for transferring control between agents.
+3. **Guardrails**: Configurable safety checks for input and output validation.
+4. **Tracing**: Built-in tracking of agent runs, allowing you to view, debug, and optimize your workflows.
+
+Explore the [`examples/`](examples/) directory to see the SDK in action.
+
+## Supported Features
+
+- [x] **Multi-Agent Workflows**: Compose and orchestrate multiple agents in a single workflow.
+- [x] **Tool Integration**: Seamlessly call tools/functions from within agent responses.
+- [x] **Handoffs**: Transfer control between agents dynamically during a run.
+- [x] **Structured Outputs**: Support for both plain text and schema-validated structured outputs.
+- [x] **Streaming Responses**: Stream agent outputs and events in real time.
+- [x] **Tracing & Debugging**: Built-in tracing for visualizing and debugging agent runs.
+- [x] **Guardrails**: Input and output validation for safety and reliability.
+- [x] **Parallelization**: Run agents or tool calls in parallel and aggregate results.
+- [x] **Human-in-the-Loop**: Integrate human approval or intervention into workflows.
+- [x] **Realtime Voice Agents**: Build realtime voice agents using WebRTC or Websockets
+- [x] **Local MCP Server Support**: Give an Agent access to a locally running MCP server to provide tools
+- [x] **Separate optimized browser package**: Dedicated package meant to run in the browser for Realtime agents.
+- [x] **Broader model support**: Use non-OpenAI models through the Vercel AI SDK adapter
+- [ ] **Long running functions**: Suspend an agent loop to execute a long-running function and revive it later <img src="https://img.shields.io/badge/Future-lightgrey" alt="Future" style="width: auto; height: 1em; vertical-align: middle;">
+- [ ] **Voice pipeline**: Chain text-based agents using speech-to-text and text-to-speech into a voice agent <img src="https://img.shields.io/badge/Future-lightgrey" alt="Future" style="width: auto; height: 1em; vertical-align: middle;">
+
+## Get started
+
+### Supported environments
+
+- Node.js 22 or later
+- Deno
+- Bun
+
+Experimental support:
+
+- Cloudflare Workers with `nodejs_compat` enabled
+
+[Check out the documentation](https://openai.github.io/openai-agents-js/guides/troubleshooting/) for more detailed information.
+
+### Installation
+
+```bash
+npm install @openai/agents
+```
+
+## Hello world example
+
+```js
+import { Agent, run } from '@openai/agents';
+
+const agent = new Agent({
+  name: 'Assistant',
+  instructions: 'You are a helpful assistant',
+});
+
+const result = await run(
+  agent,
+  'Write a haiku about recursion in programming.',
+);
+console.log(result.finalOutput);
+// Code within the code,
+// Functions calling themselves,
+// Infinite loop's dance.
+```
+
+(_If running this, ensure you set the `OPENAI_API_KEY` environment variable_)
+
+## Functions example
+
+```js
+import { z } from 'zod';
+import { Agent, run, tool } from '@openai/agents';
+
+const getWeatherTool = tool({
+  name: 'get_weather',
+  description: 'Get the weather for a given city',
+  parameters: z.object({ city: z.string() }),
+  execute: async (input) => {
+    return `The weather in ${input.city} is sunny`;
+  },
+});
+
+const agent = new Agent({
+  name: 'Data agent',
+  instructions: 'You are a data agent',
+  tools: [getWeatherTool],
+});
+
+async function main() {
+  const result = await run(agent, 'What is the weather in Tokyo?');
+  console.log(result.finalOutput);
+}
+
+main().catch(console.error);
+```
+
+## Handoffs example
+
+```js
+import { z } from 'zod';
+import { Agent, run, tool } from '@openai/agents';
+
+const getWeatherTool = tool({
+  name: 'get_weather',
+  description: 'Get the weather for a given city',
+  parameters: z.object({ city: z.string() }),
+  execute: async (input) => {
+    return `The weather in ${input.city} is sunny`;
+  },
+});
+
+const dataAgent = new Agent({
+  name: 'Data agent',
+  instructions: 'You are a data agent',
+  handoffDescription: 'You know everything about the weather',
+  tools: [getWeatherTool],
+});
+
+// Use Agent.create method to ensure the finalOutput type considers handoffs
+const agent = Agent.create({
+  name: 'Basic test agent',
+  instructions: 'You are a basic agent',
+  handoffs: [dataAgent],
+});
+
+async function main() {
+  const result = await run(agent, 'What is the weather in San Francisco?');
+  console.log(result.finalOutput);
+}
+
+main().catch(console.error);
+```
+
+## Voice Agent
+
+```js
+import { z } from 'zod';
+import { RealtimeAgent, RealtimeSession, tool } from '@openai/agents-realtime';
+
+const getWeatherTool = tool({
+  name: 'get_weather',
+  description: 'Get the weather for a given city',
+  parameters: z.object({ city: z.string() }),
+  execute: async (input) => {
+    return `The weather in ${input.city} is sunny`;
+  },
+});
+
+const agent = new RealtimeAgent({
+  name: 'Data agent',
+  instructions: 'You are a data agent',
+  tools: [getWeatherTool],
+});
+
+// Intended to be run the browser
+const { apiKey } = await fetch('/path/to/ephemerial/key/generation').then(
+  (resp) => resp.json(),
+);
+// automatically configures audio input/output so start talking
+const session = new RealtimeSession(agent);
+await session.connect({ apiKey });
+```
+
+## The agent loop
+
+When you call `Runner.run()`, the SDK executes a loop until a final output is produced.
+
+1. The agent is invoked with the given input, using the model and settings configured on the agent (or globally).
+2. The LLM returns a response, which may include tool calls or handoff requests.
+3. If the response contains a final output (see below), the loop ends and the result is returned.
+4. If the response contains a handoff, the agent is switched to the new agent and the loop continues.
+5. If there are tool calls, the tools are executed, their results are appended to the message history, and the loop continues.
+
+You can control the maximum number of iterations with the `maxTurns` parameter.
+
+### Final output
+
+The final output is the last thing the agent produces in the loop.
+
+1. If the agent has an `outputType` (structured output), the loop ends when the LLM returns a response matching that type.
+2. If there is no `outputType` (plain text), the first LLM response without tool calls or handoffs is considered the final output.
+
+**Summary of the agent loop:**
+
+- If the current agent has an `outputType`, the loop runs until structured output of that type is produced.
+- If not, the loop runs until a message is produced with no tool calls or handoffs.
+
+### Error handling
+
+- If the maximum number of turns is exceeded, a `MaxTurnsExceededError` is thrown.
+- If a guardrail is triggered, a `GuardrailTripwireTriggered` exception is raised.
+
+## Documentation
+
+To view the documentation locally:
+
+```bash
+pnpm docs:dev
+```
+
+Then visit [http://localhost:4321](http://localhost:4321) in your browser.
+
+## Development
+
+If you want to contribute or edit the SDK/examples:
+
+1. Install dependencies
+
+   ```bash
+   pnpm install
+   ```
+
+2. Build the project
+
+   ```bash
+   pnpm build
+   ```
+
+3. Run tests, linter, etc. (add commands as appropriate for your project)
+
+## Acknowledgements
+
+We'd like to acknowledge the excellent work of the open-source community, especially:
+
+- [zod](https://github.com/colinhacks/zod) (schema validation)
+- [Starlight](https://github.com/withastro/starlight)
+- [vite](https://github.com/vitejs/vite) and [vitest](https://github.com/vitest-dev/vitest)
+- [pnpm](https://pnpm.io/)
+- [Next.js](https://github.com/vercel/next.js)
+
+We're committed to building the Agents SDK as an open source framework so others in the community can expand on our approach.
+
+For more details, see the [documentation](https://openai.github.io/openai-agents-js) or explore the [`examples/`](examples/) directory.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from '@openai/agents-core';
+export * from '@openai/agents-openai';
+export * as realtime from '@openai/agents-realtime';

package/dist/index.js

@@ -0,0 +1,9 @@
+import { setDefaultModelProvider } from '@openai/agents-core';
+import { OpenAIProvider } from '@openai/agents-openai';
+import { setDefaultOpenAITracingExporter } from '@openai/agents-openai';
+setDefaultModelProvider(new OpenAIProvider());
+setDefaultOpenAITracingExporter();
+export * from '@openai/agents-core';
+export * from '@openai/agents-openai';
+export * as realtime from '@openai/agents-realtime';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB;OACtD,EAAE,cAAc,EAAE,MAAM,uBAAuB;OAC/C,EAAE,+BAA+B,EAAE,MAAM,uBAAuB;AAEvE,uBAAuB,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AAC9C,+BAA+B,EAAE,CAAC;cAEpB,qBAAqB;cACrB,uBAAuB;OAC9B,KAAK,QAAQ,MAAM,yBAAyB"}

package/dist/index.mjs

@@ -0,0 +1,9 @@
+import { setDefaultModelProvider } from '@openai/agents-core';
+import { OpenAIProvider } from '@openai/agents-openai';
+import { setDefaultOpenAITracingExporter } from '@openai/agents-openai';
+setDefaultModelProvider(new OpenAIProvider());
+setDefaultOpenAITracingExporter();
+export * from '@openai/agents-core';
+export * from '@openai/agents-openai';
+export * as realtime from '@openai/agents-realtime';
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB;OACtD,EAAE,cAAc,EAAE,MAAM,uBAAuB;OAC/C,EAAE,+BAA+B,EAAE,MAAM,uBAAuB;AAEvE,uBAAuB,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AAC9C,+BAA+B,EAAE,CAAC;cAEpB,qBAAqB;cACrB,uBAAuB;OAC9B,KAAK,QAAQ,MAAM,yBAAyB"}

package/dist/metadata.d.ts

@@ -0,0 +1,12 @@
+export declare const METADATA: {
+    name: string;
+    version: string;
+    versions: {
+        "@openai/agents": string;
+        "@openai/agents-core": string;
+        "@openai/agents-openai": string;
+        "@openai/agents-realtime": string;
+        openai: string;
+    };
+};
+export default METADATA;

package/dist/metadata.js

@@ -0,0 +1,14 @@
+// This file is automatically generated
+export const METADATA = {
+    "name": "@openai/agents",
+    "version": "0.0.1",
+    "versions": {
+        "@openai/agents": "0.0.1",
+        "@openai/agents-core": "workspace:*",
+        "@openai/agents-openai": "workspace:*",
+        "@openai/agents-realtime": "workspace:*",
+        "openai": "^5.0.1"
+    }
+};
+export default METADATA;
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,uCAAuC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,gBAAgB;IACxB,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE;QACV,gBAAgB,EAAE,OAAO;QACzB,qBAAqB,EAAE,aAAa;QACpC,uBAAuB,EAAE,aAAa;QACtC,yBAAyB,EAAE,aAAa;QACxC,QAAQ,EAAE,QAAQ;KACnB;CACF,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/metadata.mjs

@@ -0,0 +1,14 @@
+// This file is automatically generated
+export const METADATA = {
+    "name": "@openai/agents",
+    "version": "0.0.1",
+    "versions": {
+        "@openai/agents": "0.0.1",
+        "@openai/agents-core": "workspace:*",
+        "@openai/agents-openai": "workspace:*",
+        "@openai/agents-realtime": "workspace:*",
+        "openai": "^5.0.1"
+    }
+};
+export default METADATA;
+//# sourceMappingURL=metadata.mjs.map

package/dist/metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.mjs","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,uCAAuC;AAEvC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAE,gBAAgB;IACxB,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE;QACV,gBAAgB,EAAE,OAAO;QACzB,qBAAqB,EAAE,aAAa;QACpC,uBAAuB,EAAE,aAAa;QACtC,yBAAyB,EAAE,aAAa;QACxC,QAAQ,EAAE,QAAQ;KACnB;CACF,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/realtime/index.d.ts

@@ -0,0 +1 @@
+export * from '@openai/agents-realtime';

package/dist/realtime/index.js

@@ -0,0 +1,2 @@
+export * from '@openai/agents-realtime';
+//# sourceMappingURL=index.js.map

package/dist/realtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"cAAc,yBAAyB"}

package/dist/realtime/index.mjs

@@ -0,0 +1,2 @@
+export * from '@openai/agents-realtime';
+//# sourceMappingURL=index.mjs.map

package/dist/realtime/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"cAAc,yBAAyB"}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from '@openai/agents-core/utils';

package/dist/utils/index.js

@@ -0,0 +1,2 @@
+export * from '@openai/agents-core/utils';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"cAAc,2BAA2B"}

package/dist/utils/index.mjs

@@ -0,0 +1,2 @@
+export * from '@openai/agents-core/utils';
+//# sourceMappingURL=index.mjs.map

package/dist/utils/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"cAAc,2BAA2B"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@openai/agents",
+  "repository": "https://github.com/openai/openai-agents-js",
+  "homepage": "https://openai.github.io/openai-agents-js/",
+  "version": "0.0.1",
+  "description": "The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.",
+  "author": "OpenAI <support@openai.com>",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./realtime": {
+      "require": {
+        "types": "./dist/realtime/index.d.ts",
+        "default": "./dist/realtime/index.js"
+      },
+      "types": "./dist/realtime/index.d.ts",
+      "default": "./dist/realtime/index.mjs"
+    },
+    "./utils": {
+      "require": {
+        "types": "./dist/utils/index.d.ts",
+        "default": "./dist/utils/index.js"
+      },
+      "types": "./dist/utils/index.d.ts",
+      "default": "./dist/utils/index.mjs"
+    }
+  },
+  "dependencies": {
+    "openai": "^5.0.1",
+    "debug": "^4.4.0",
+    "@openai/agents-core": "0.0.1",
+    "@openai/agents-realtime": "0.0.1",
+    "@openai/agents-openai": "0.0.1"
+  },
+  "keywords": [
+    "openai",
+    "agents",
+    "ai",
+    "agentic"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/debug": "^4.1.12"
+  },
+  "files": [
+    "dist"
+  ],
+  "typesVersions": {
+    "*": {
+      "realtime": [
+        "dist/realtime/index.d.ts"
+      ],
+      "utils": [
+        "dist/utils/index.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "prebuild": "tsx ../../scripts/embedMeta.ts",
+    "build": "tsc",
+    "build-check": "tsc --noEmit -p ./tsconfig.test.json"
+  }
+}