Skip to content

Commit a8cd914

Browse files
xumaplexumaple
authored
AI-266: Add @temporalio/openai-agents sample suite (#479)
* AI-266: Add @temporalio/openai-agents sample suite Fourteen self-contained samples demonstrating how to run OpenAI Agents SDK agents as Temporal Workflows with the @temporalio/openai-agents integration: the basic building blocks, handoffs, agent patterns, sessions, human approval, hosted/Nexus/MCP tools, tracing, model providers, reasoning content, a research bot, and a customer-service chat. Each sample is a standalone package with a fake-model Worker test that runs without an API key, and the suite is wired into the pnpm workspace, CI, and the samples list. * refactor down * AI-266: Restructure openai-agents samples to standard single-src layout Move each scenario from openai-agents/<feature>/src/ to openai-agents/src/<feature>/, letting the package use the shared tsconfig (removed from TSCONFIG_EXCLUDE). Rename two scenarios to feature-based names: research-bot -> multi-agent, customer-service -> stateful-conversation. Add an Ollama start snippet to the model-providers README. * AI-266: Reformat openai-agents README and reasoning-content to satisfy prettier * AI-266: Give openai-agents a per-scenario post-create message The shared post-create pointed users at `npm run start.watch`/`npm run workflow`, which don't exist in openai-agents' per-scenario layout. Exclude it from the shared copy and ship instructions matching how the sample runs.
1 parent 110863e commit a8cd914

117 files changed

Lines changed: 6669 additions & 27 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ jobs:
6969
workflow-streams
7070
message-passing/introduction
7171
message-passing/safe-message-handlers
72+
openai-agents
7273
polling/infrequent
7374
)
7475
for project in "${projects[@]}"; do

‎.scripts/copy-shared-files.mjs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ const GITIGNORE_EXCLUDE = [
4242
'nestjs-exchange-rates',
4343
];
4444
const ESLINTRC_EXCLUDE = [
45+
'openai-agents',
4546
'nextjs-ecommerce-oneclick',
4647
'monorepo-folders',
4748
'fetch-esm',
@@ -63,6 +64,7 @@ const ESLINTIGNORE_EXCLUDE = [
6364
];
6465

6566
const POST_CREATE_EXCLUDE = [
67+
'openai-agents',
6668
'schedules',
6769
'timer-examples',
6870
'query-subscriptions',

‎.scripts/list-of-samples.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
"nexus-cancellation",
3333
"nexus-hello",
3434
"nexus-messaging",
35+
"openai-agents",
3536
"patching-api",
3637
"production",
3738
"protobufs",

‎README.md‎

Lines changed: 37 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,25 @@
33
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
44
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
55

6-
- [samples-typescript](#samples-typescript)
7-
- [Running](#running)
8-
- [Locally](#locally)
9-
- [Scaffold](#scaffold)
10-
- [Samples](#samples)
11-
- [Basic](#basic)
12-
- [API demos](#api-demos)
13-
- [Activity APIs and design patterns](#activity-apis-and-design-patterns)
14-
- [Nexus APIs](#nexus-apis)
15-
- [Workflow APIs](#workflow-apis)
16-
- [Production APIs](#production-apis)
17-
- [Advanced APIs](#advanced-apis)
18-
- [Test APIs](#test-apis)
19-
- [Full-stack apps](#full-stack-apps)
20-
- [External apps \& libraries](#external-apps--libraries)
21-
- [Contributing](#contributing)
22-
- [Dependencies](#dependencies)
23-
- [Upgrading the SDK version in `package.json`s](#upgrading-the-sdk-version-in-packagejsons)
24-
- [Config files](#config-files)
6+
- [Running](#running)
7+
- [Locally](#locally)
8+
- [Scaffold](#scaffold)
9+
- [Samples](#samples)
10+
- [Basic](#basic)
11+
- [API demos](#api-demos)
12+
- [Activity APIs and design patterns](#activity-apis-and-design-patterns)
13+
- [Nexus APIs](#nexus-apis)
14+
- [Workflow APIs](#workflow-apis)
15+
- [Production APIs](#production-apis)
16+
- [Advanced APIs](#advanced-apis)
17+
- [Test APIs](#test-apis)
18+
- [AI / LLM](#ai--llm)
19+
- [Full-stack apps](#full-stack-apps)
20+
- [External apps & libraries](#external-apps--libraries)
21+
- [Contributing](#contributing)
22+
- [Dependencies](#dependencies)
23+
- [Upgrading the SDK version in `package.json`s](#upgrading-the-sdk-version-in-packagejsons)
24+
- [Config files](#config-files)
2525

2626
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2727

@@ -161,6 +161,24 @@ and you'll be given the list of sample options.
161161
- [**Mocha with code coverage or Jest**](https://github.com/temporalio/samples-typescript/tree/main/activities-examples#testing)
162162
- [**Time skipping**](https://github.com/temporalio/samples-typescript/tree/main/timer-examples#testing)
163163

164+
#### AI / LLM
165+
166+
- [**OpenAI Agents**](./openai-agents): Run [OpenAI Agents SDK](https://github.com/openai/openai-agents-js) agents as Temporal Workflows with the `@temporalio/openai-agents` integration. The [`openai-agents/`](./openai-agents) directory contains fourteen samples:
167+
- [**Basic**](./openai-agents/basic): A single agent plus the building blocks — Activity-backed and inline tools, local-Activity tools, agent context, structured output, per-run model override, and dynamic instructions.
168+
- [**Handoffs**](./openai-agents/handoffs): A triage agent routes each request to a specialist agent, using both the `Agent[]` and `handoff()` forms and a per-handoff input filter.
169+
- [**Agent Patterns**](./openai-agents/agent-patterns): Multi-agent orchestration patterns — deterministic chaining, parallelization, LLM-as-judge, agents-as-tools, and input/output guardrails.
170+
- [**Sessions**](./openai-agents/sessions): Conversation history with `WorkflowSafeMemorySession`, including carrying history across a `continueAsNew` boundary.
171+
- [**Human Approval**](./openai-agents/human-approval): A human-in-the-loop tool that pauses the run for an `approve` Signal, then resumes by serializing and rehydrating the run state across `continueAsNew`.
172+
- [**Tools**](./openai-agents/tools): Server-side hosted tools — web search, image generation, and code interpreter — executed by the model provider in the model Activity.
173+
- [**Tracing**](./openai-agents/tracing): The three supported tracing paths — a custom `TracingProcessor`, the OpenAI hosted exporter, and OpenTelemetry — plus `temporal:*` orchestration spans.
174+
- [**Model Providers**](./openai-agents/model-providers): Pass a custom `ModelProvider` to point an agent at any OpenAI-compatible endpoint.
175+
- [**Reasoning Content**](./openai-agents/reasoning-content): Read a reasoning model's `reasoning_content` field by calling the `openai` SDK directly from an Activity.
176+
- [**MCP**](./openai-agents/mcp): Stateless and stateful Model Context Protocol servers (stdio, Streamable HTTP, SSE, and prompt servers) running locally.
177+
- [**Hosted MCP**](./openai-agents/hosted-mcp): A `HostedMCPTool` the model calls server-side, with and without a Signal-driven approval round trip.
178+
- [**Research Bot**](./openai-agents/research-bot): A planner agent fans out concurrent web searches and a writer agent synthesizes a final report.
179+
- [**Customer Service**](./openai-agents/customer-service): A long-running, multi-turn Workflow driven by Updates and Queries, with triage handoffs and `continueAsNew` to bound history.
180+
- [**Nexus Tools**](./openai-agents/nexus-tools): Expose a Nexus Operation as an agent tool with `nexusOperationAsTool`.
181+
164182
### Full-stack apps
165183

166184
- **Next.js**:

‎openai-agents/.eslintignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
lib
3+
.eslintrc.js

‎openai-agents/.eslintrc.js‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
const { builtinModules } = require('module');
2+
3+
const ALLOWED_NODE_BUILTINS = new Set(['assert']);
4+
5+
module.exports = {
6+
root: true,
7+
parser: '@typescript-eslint/parser',
8+
parserOptions: {
9+
project: './tsconfig.json',
10+
tsconfigRootDir: __dirname,
11+
},
12+
plugins: ['@typescript-eslint', 'deprecation'],
13+
extends: [
14+
'eslint:recommended',
15+
'plugin:@typescript-eslint/eslint-recommended',
16+
'plugin:@typescript-eslint/recommended',
17+
'prettier',
18+
],
19+
rules: {
20+
// recommended for safety
21+
'@typescript-eslint/no-floating-promises': 'error', // forgetting to await Activities and Workflow APIs is bad
22+
'deprecation/deprecation': 'warn',
23+
24+
// code style preference
25+
'object-shorthand': ['error', 'always'],
26+
27+
// relaxed rules, for convenience
28+
'@typescript-eslint/no-unused-vars': [
29+
'warn',
30+
{
31+
argsIgnorePattern: '^_',
32+
varsIgnorePattern: '^_',
33+
},
34+
],
35+
'@typescript-eslint/no-explicit-any': 'off',
36+
},
37+
overrides: [
38+
{
39+
files: ['src/*/workflows.ts', 'src/*/workflows-*.ts', 'src/*/workflows/*.ts'],
40+
rules: {
41+
'no-restricted-imports': [
42+
'error',
43+
...builtinModules.filter((m) => !ALLOWED_NODE_BUILTINS.has(m)).flatMap((m) => [m, `node:${m}`]),
44+
],
45+
},
46+
},
47+
],
48+
};

‎openai-agents/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
lib
2+
node_modules

‎openai-agents/.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
package-lock=false

‎openai-agents/.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22

‎openai-agents/.post-create‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
To begin development, install the Temporal CLI:
2+
3+
Mac: {cyan brew install temporal}
4+
Other: Download and extract the latest release from https://github.com/temporalio/cli/releases/latest
5+
6+
Start Temporal Server:
7+
8+
{cyan temporal server start-dev}
9+
10+
Use Node version 18+ (v22.x is recommended):
11+
12+
Mac: {cyan brew install node@22}
13+
Other: https://nodejs.org/en/download/
14+
15+
This sample has several scenarios under {cyan src/}. Using two other shells, start a Worker for one scenario and run its client (example: {cyan basic}):
16+
17+
{cyan OPENAI_API_KEY=<your-key> npx ts-node src/basic/worker.ts}
18+
{cyan npx ts-node src/basic/client.ts hello-world}
19+
20+
See README.md for the full list of scenarios.

0 commit comments

Comments
 (0)