class documentation

Temporal plugin for integrating OpenAI agents with Temporal workflows.

Warning

This class is experimental and may change in future versions. Use with caution in production environments.

This plugin provides seamless integration between the OpenAI Agents SDK and Temporal workflows. It automatically configures the necessary interceptors, activities, and data converters to enable OpenAI agents to run within Temporal workflows with proper tracing and model execution.

The plugin: 1. Configures the Pydantic data converter for type-safe serialization 2. Sets up tracing interceptors for OpenAI agent interactions 3. Registers model execution activities 4. Automatically registers MCP server activities and manages their lifecycles 5. Manages the OpenAI agent runtime overrides during worker execution

Example

>>> from temporalio.client import Client
>>> from temporalio.worker import Worker
>>> from temporalio.contrib.openai_agents import OpenAIAgentsPlugin, ModelActivityParameters, StatelessMCPServerProvider
>>> from agents.mcp import MCPServerStdio
>>> from datetime import timedelta
>>>
>>> # Configure model parameters
>>> model_params = ModelActivityParameters(
...     start_to_close_timeout=timedelta(seconds=30),
...     retry_policy=RetryPolicy(maximum_attempts=3)
... )
>>>
>>> # Create MCP servers
>>> filesystem_server = StatelessMCPServerProvider(MCPServerStdio(
...     name="Filesystem Server",
...     params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}
... ))
>>>
>>> # Create plugin with MCP servers
>>> plugin = OpenAIAgentsPlugin(
...     model_params=model_params,
...     mcp_server_providers=[filesystem_server]
... )
>>>
>>> # Use with client and worker
>>> client = await Client.connect(
...     "localhost:7233",
...     plugins=[plugin]
... )
>>> worker = Worker(
...     client,
...     task_queue="my-task-queue",
...     workflows=[MyWorkflow],
... )
Parameters
model_paramsConfiguration parameters for Temporal activity execution of model calls. If None, default parameters will be used.
model_providerOptional model provider for custom model implementations. Useful for testing or custom model integrations.
mcp_server_providersSequence of MCP servers to automatically register with the worker. The plugin will wrap each server in a TemporalMCPServer if needed and manage their connection lifecycles tied to the worker lifetime. This is the recommended way to use MCP servers with Temporal workflows.
Method __init__ Initialize the OpenAI agents plugin.
Method configure_client Configure the Temporal client for OpenAI agents integration.
Method configure_replayer Configure the replayer for OpenAI Agents.
Method configure_worker Configure the Temporal worker for OpenAI agents integration.
Async Method connect_service_client No modifications to service client
Method init_client_plugin Set the next client plugin
Method init_worker_plugin Set the next worker plugin
Async Method run_replayer Set the OpenAI Overrides during replay
Async Method run_worker Run the worker with OpenAI agents temporal overrides.
Instance Variable next_client_plugin Undocumented
Instance Variable next_worker_plugin Undocumented
Static Method _data_converter Undocumented
Instance Variable _mcp_server_providers Undocumented
Instance Variable _model_params Undocumented
Instance Variable _model_provider Undocumented

Inherited from Plugin:

Method name Get the name of this plugin. Can be overridden if desired to provide a more appropriate name.
def __init__(self, model_params: ModelActivityParameters | None = None, model_provider: ModelProvider | None = None, mcp_server_providers: Sequence[StatelessMCPServerProvider | StatefulMCPServerProvider] = ()): (source)

Initialize the OpenAI agents plugin.

Parameters
model_params:ModelActivityParameters | NoneConfiguration parameters for Temporal activity execution of model calls. If None, default parameters will be used.
model_provider:ModelProvider | NoneOptional model provider for custom model implementations. Useful for testing or custom model integrations.
mcp_server_providers:Sequence[StatelessMCPServerProvider | StatefulMCPServerProvider]Sequence of MCP servers to automatically register with the worker. Each server will be wrapped in a TemporalMCPServer if not already wrapped, and their activities will be automatically registered with the worker. The plugin manages the connection lifecycle of these servers.
def configure_client(self, config: ClientConfig) -> ClientConfig: (source)

Configure the Temporal client for OpenAI agents integration.

This method sets up the Pydantic data converter to enable proper serialization of OpenAI agent objects and responses.

Parameters
config:ClientConfigThe client configuration to modify.
Returns
ClientConfigThe modified client configuration.
def configure_replayer(self, config: ReplayerConfig) -> ReplayerConfig: (source)

Configure the replayer for OpenAI Agents.

def configure_worker(self, config: WorkerConfig) -> WorkerConfig: (source)

Configure the Temporal worker for OpenAI agents integration.

This method adds the necessary interceptors and activities for OpenAI agent execution: - Adds tracing interceptors for OpenAI agent interactions - Registers model execution activities

Parameters
config:WorkerConfigThe worker configuration to modify.
Returns
WorkerConfigThe modified worker configuration.
async def connect_service_client(self, config: temporalio.service.ConnectConfig) -> temporalio.service.ServiceClient: (source)

No modifications to service client

def init_client_plugin(self, next: temporalio.client.Plugin): (source)

Set the next client plugin

def init_worker_plugin(self, next: temporalio.worker.Plugin): (source)

Set the next worker plugin

@asynccontextmanager
async def run_replayer(self, replayer: Replayer, histories: AsyncIterator[temporalio.client.WorkflowHistory]) -> AsyncIterator[AsyncIterator[WorkflowReplayResult]]: (source)

Set the OpenAI Overrides during replay

async def run_worker(self, worker: Worker): (source)

Run the worker with OpenAI agents temporal overrides.

This method sets up the necessary runtime overrides for OpenAI agents to work within the Temporal worker context, including custom runners and trace providers.

Parameters
worker:WorkerThe worker instance to run.
next_client_plugin = (source)

Undocumented

next_worker_plugin = (source)

Undocumented

@staticmethod
def _data_converter(converter: DataConverter | None) -> DataConverter: (source)

Undocumented

_mcp_server_providers = (source)

Undocumented

_model_params = (source)

Undocumented

_model_provider = (source)

Undocumented