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.

Inherited from SimplePlugin:

Method configure_client See base class.
Method configure_replayer See base class.
Method configure_worker See base class.
Async Method connect_service_client See base class.
Method name See base class.
Async Method run_replayer See base class.
Async Method run_worker See base class.
Instance Variable activities Undocumented
Instance Variable client_interceptors Undocumented
Instance Variable data_converter Undocumented
Instance Variable nexus_service_handlers Undocumented
Instance Variable run_context Undocumented
Instance Variable worker_interceptors Undocumented
Instance Variable workflow_failure_exception_types Undocumented
Instance Variable workflow_runner Undocumented
Instance Variable workflows Undocumented
Instance Variable _name Undocumented
def __init__(self, model_params: ModelActivityParameters | None = None, model_provider: ModelProvider | None = None, mcp_server_providers: Sequence[StatelessMCPServerProvider | StatefulMCPServerProvider] = (), register_activities: bool = True): (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.
register_activities:boolWhether to register activities during the worker execution. This can be disabled on some workers to allow a separation of workflows and activities but should not be disabled on all workers, or agents will not be able to progress.