|
| 1 | +# OpenAI Agents |
| 2 | + |
| 3 | +These samples use the `@temporalio/openai-agents` integration to run [OpenAI Agents SDK](https://github.com/openai/openai-agents-js) agents as Temporal Workflows. Agent orchestration — the agent loop, handoffs, tool calls, and guardrails — runs inside the Workflow, while model calls run as durable Activities, so they retry on failure and are not repeated during Workflow replay. |
| 4 | + |
| 5 | +Each subdirectory is a standalone sample with its own `package.json` and README. The integration package itself is documented in the [`@temporalio/openai-agents` README](https://github.com/temporalio/sdk-typescript/tree/main/packages/openai-agents). |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +These apply to every sample in this directory: |
| 10 | + |
| 11 | +- A running Temporal dev server: `temporal server start-dev`. |
| 12 | +- Node 22 or later. |
| 13 | +- An OpenAI API key: `export OPENAI_API_KEY=...`. |
| 14 | +- Dependencies installed in the sample directory: `npm install`. |
| 15 | + |
| 16 | +Each sample's README describes how to start its Worker and run its scenarios. |
| 17 | + |
| 18 | +## Samples |
| 19 | + |
| 20 | +| Sample | Demonstrates | |
| 21 | +| :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | |
| 22 | +| [`basic`](./basic) | A single agent plus the core building blocks: Activity-backed and inline tools, local-Activity tools, agent context, structured output, per-run model override, and dynamic instructions. | |
| 23 | +| [`handoffs`](./handoffs) | A triage agent routes each request to a specialist agent, using both the `Agent[]` and `handoff()` forms and a per-handoff input filter. | |
| 24 | +| [`agent-patterns`](./agent-patterns) | Multi-agent orchestration patterns: deterministic chaining, parallelization, LLM-as-judge, agents-as-tools, and input/output guardrails. | |
| 25 | +| [`sessions`](./sessions) | Conversation history with `WorkflowSafeMemorySession`, including carrying history across a `continueAsNew` boundary. | |
| 26 | +| [`human-approval`](./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`. | |
| 27 | +| [`tools`](./tools) | Server-side hosted tools — web search, image generation, and code interpreter — executed by the model provider during the model Activity. | |
| 28 | +| [`tracing`](./tracing) | The three supported tracing paths: a custom `TracingProcessor`, the OpenAI hosted exporter, and OpenTelemetry, plus `temporal:*` orchestration spans. | |
| 29 | +| [`model-providers`](./model-providers) | Pass a custom `ModelProvider` to point an agent at any OpenAI-compatible endpoint. | |
| 30 | +| [`reasoning-content`](./reasoning-content) | Read a reasoning model's `reasoning_content` field by calling the `openai` SDK directly from an Activity. | |
| 31 | +| [`mcp`](./mcp) | Stateless and stateful Model Context Protocol servers (stdio, Streamable HTTP, SSE, and prompt servers) running locally. | |
| 32 | +| [`hosted-mcp`](./hosted-mcp) | A `HostedMCPTool` the model calls server-side, with and without a Signal-driven approval round trip. | |
| 33 | +| [`research-bot`](./research-bot) | A planner agent fans out concurrent web searches and a writer agent synthesizes a final report. | |
| 34 | +| [`customer-service`](./customer-service) | A long-running, multi-turn Workflow driven by Updates and Queries, with triage handoffs and `continueAsNew` to bound history. | |
| 35 | +| [`nexus-tools`](./nexus-tools) | Expose a [Nexus](https://docs.temporal.io/nexus) Operation as an agent tool with `nexusOperationAsTool`. | |
| 36 | + |
| 37 | +## Feature support |
| 38 | + |
| 39 | +Any OpenAI Agents SDK `ModelProvider` can drive the model Activity. The provider runs in the Activity, never inside the Workflow sandbox. |
| 40 | + |
| 41 | +| Feature | Status | Notes | |
| 42 | +| :---------------------- | :------------ | :-------------------------------------------------------------------------------------- | |
| 43 | +| Multi-turn agents | Supported | Agent loop runs durably in the Workflow | |
| 44 | +| Handoffs | Supported | `Agent` and `handoff()` forms | |
| 45 | +| Inline function tools | Supported | Must be deterministic | |
| 46 | +| Activity-backed tools | Supported | Via `activityAsTool()` | |
| 47 | +| Nexus operation tools | Supported | Via `nexusOperationAsTool()` | |
| 48 | +| Nested agent tools | Supported | Via `agentAsTool()` | |
| 49 | +| Hosted tools | Supported | Executed server-side by the model provider | |
| 50 | +| Stateless MCP servers | Supported | Via `StatelessMCPServerProvider` and `statelessMcpServer()` | |
| 51 | +| Stateful MCP servers | Supported | Via `StatefulMCPServerProvider` and `statefulMcpServer()` | |
| 52 | +| Sessions | Supported | Via `WorkflowSafeMemorySession`; upstream `MemorySession` is rejected | |
| 53 | +| Run state and approvals | Supported | Serialize with `result.state.toString()` and rehydrate with `RunState.fromString` | |
| 54 | +| Guardrails | Supported | Guardrail callbacks must be deterministic | |
| 55 | +| Tracing | Supported | OpenAI hosted traces, custom `TracingProcessor`s, OTel, and optional `temporal:*` spans | |
| 56 | +| Agent context | Supported | Activity tools receive a copy | |
| 57 | +| `continueAsNew` | Supported | Plugin config propagates to the continuation | |
| 58 | +| Child Workflows | Supported | Plugin config propagates to children | |
| 59 | +| Local Activities | Supported | Set `useLocalActivity: true` in `modelParams` | |
| 60 | +| Model override per run | Supported | `runConfig.model` accepts a string model name | |
| 61 | +| Streaming | Not supported | Use `runner.run()` | |
| 62 | +| Voice agents | Not supported | | |
0 commit comments