Feat/OpenAI agents plugin sandbox support (#1452)

Add SandboxAgent support to Temporal OpenAI Agents plugin

Enable workflows to use the OpenAI Agents SDK's SandboxAgent by routing all sandbox lifecycle and I/O operations through Temporal activities. The user passes a real sandbox client (e.g. DaytonaSandboxClient) to OpenAIAgentsPlugin(sandbox_client=...) and the plugin handles the rest — no direct imports from the sandbox subpackage are needed.

Key changes:

Add sandbox/ subpackage with internal modules for:

- TemporalSandboxClient: workflow-side client that dispatches create/resume/delete as activities
- TemporalSandboxSession: workflow-side session that routes exec, read, write, and other I/O through activities
- TemporalSandboxActivities: worker-side activity implementations that delegate to the real BaseSandboxClient/BaseSandboxSession
- Pydantic activity arg/result models for serialization

Update TemporalOpenAIRunner to detect SandboxAgent in the agent graph and automatically inject TemporalSandboxClient when run_config.sandbox is configured

Update OpenAIAgentsPlugin to accept sandbox_client and register sandbox activities on the worker

Add tests covering:

- SandboxAgent detection in agent graphs (direct, handoff, circular)
- Validation errors (missing config, wrong client type)
- Activity delegation (each activity correctly calls the real client/session)
- Session caching and eviction in TemporalSandboxActivities
- End-to-end integration test running sandbox activities through a real Temporal workflow

Author: JasonSteving99

pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
 grpc = ["grpcio>=1.48.2,<2"]
 opentelemetry = ["opentelemetry-api>=1.11.1,<2", "opentelemetry-sdk>=1.11.1,<2"]
 pydantic = ["pydantic>=2.0.0,<3"]
-openai-agents = ["openai-agents>=0.3,<0.7", "mcp>=1.9.4, <2"]
+openai-agents = ["openai-agents>=0.14.0", "mcp>=1.9.4, <2"]
 google-adk = ["google-adk>=1.27.0,<2"]
 langsmith = ["langsmith>=0.7.0,<0.8"]
 lambda-worker-otel = [
@@ -71,8 +71,8 @@ dev = [
   "pytest-cov>=6.1.1",
   "httpx>=0.28.1",
   "pytest-pretty>=1.3.0",
-  "openai-agents>=0.3,<0.7; python_version >= '3.14'",
-  "openai-agents[litellm]>=0.3,<0.7; python_version < '3.14'",
+  "openai-agents>=0.14.0; python_version >= '3.14'",
+  "openai-agents[litellm]>=0.14.0; python_version < '3.14'",
   "litellm>=1.83.0",
   "openinference-instrumentation-google-adk>=0.1.8",
   "googleapis-common-protos==1.70.0",

temporalio/contrib/openai_agents/README.md

@@ -17,6 +17,7 @@ This document is organized as follows:
 - **[Background Concepts](#core-concepts).** Background on durable execution and AI agents.
 - **[Full Example](#full-example)** Running the Hello World Durable Agent example.
 - **[Tool Calling](#tool-calling).** Calling agent Tools in Temporal.
+- **[Sandbox Support](#sandbox-support).** Running sandbox agents in Temporal.
 - **[Feature Support](#feature-support).** Compatibility matrix.
 
 The [samples repository](https://github.com/temporalio/samples-python/tree/main/openai_agents) contains examples including basic usage, common agent patterns, and more complete samples.
@@ -450,6 +451,131 @@ To recover from such failures, you need to implement your own application-level
 
 For network-accessible MCP servers, you can also use `HostedMCPTool` from the OpenAI Agents SDK, which uses an MCP client hosted by OpenAI.
 
+## Sandbox Support
+
+⚠️ **Pre-release** - This functionality is subject to change prior to General Availability.
+
+The sandbox integration lets `SandboxAgent` from the OpenAI Agents SDK execute inside a remote or local sandbox (Daytona, Docker, E2B, local Unix, etc.) while keeping all coordination durable in Temporal.
+
+Every sandbox operation — creating a session, running commands, reading/writing files, PTY interactions — is dispatched as a Temporal activity. This means sandbox work is fully observable, retryable, and recoverable like any other activity, and sandbox session state is serialized with the workflow so it survives worker restarts.
+
+### Architecture
+
+```text
+Workflow Code
+  ↓
+temporal_sandbox_client("daytona")   [returns TemporalSandboxClient]
+  ↓
+SandboxAgent.run(run_config=RunConfig(sandbox=SandboxRunConfig(client=...)))
+  ↓
+sandbox agent calls session.exec / session.read / session.write / …
+  ↓
+TemporalSandboxSession routes each call as a Temporal activity
+("daytona-sandbox_session_exec", "daytona-sandbox_session_read", …)
+  ↓
+SandboxClientProvider activities on the worker call the real sandbox client
+  ↓
+Actual sandbox backend (Daytona, Docker, local, …)
+```
+
+### Worker Configuration
+
+Register one or more `SandboxClientProvider` instances with the plugin. Each provider pairs a unique name with a real `BaseSandboxClient` implementation. The plugin automatically registers all required activities on the worker.
+
+```python
+import asyncio
+import docker
+from temporalio.client import Client
+from temporalio.worker import Worker
+from temporalio.contrib.openai_agents import OpenAIAgentsPlugin, SandboxClientProvider, ModelActivityParameters
+from agents.extensions.sandbox.daytona import DaytonaSandboxClient
+from agents.extensions.sandbox.unix_local import UnixLocalSandboxClient
+
+async def main():
+    client = await Client.connect(
+        "localhost:7233",
+        plugins=[
+            OpenAIAgentsPlugin(
+                model_params=ModelActivityParameters(
+                    start_to_close_timeout=timedelta(seconds=30)
+                ),
+                sandbox_clients=[
+                    SandboxClientProvider("daytona", DaytonaSandboxClient()),
+                    SandboxClientProvider("local", UnixLocalSandboxClient()),
+                ],
+            ),
+        ],
+    )
+
+    worker = Worker(
+        client,
+        task_queue="my-task-queue",
+        workflows=[MyWorkflow],
+    )
+    await worker.run()
+```
+
+Provider names must be unique. Each name becomes the prefix for that backend's activities, allowing multiple backends to coexist on a single worker.
+
+### Workflow Usage
+
+In the workflow, use `temporal_sandbox_client()` to create a reference to a registered backend by name. Pass it to `SandboxRunConfig` inside `RunConfig`:
+
+```python
+from temporalio import workflow
+from temporalio.contrib.openai_agents.workflow import temporal_sandbox_client
+from agents import Runner
+from agents.sandbox import SandboxAgent, SandboxRunConfig
+from agents.run import RunConfig
+
+@workflow.defn
+class MyWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        agent = SandboxAgent(
+            name="Coding Assistant",
+            instructions="You are a helpful coding assistant with access to a sandbox.",
+        )
+
+        result = await Runner.run(
+            agent,
+            prompt,
+            run_config=RunConfig(
+                sandbox=SandboxRunConfig(
+                    client=temporal_sandbox_client("daytona"),
+                    options=DaytonaSandboxClientOptions(pause_on_exit=False),
+                ),
+            ),
+        )
+        return result.final_output
+```
+
+The name passed to `temporal_sandbox_client()` must exactly match the name used in `SandboxClientProvider` on the worker.
+
+### Multiple Backends
+
+A single workflow can target different backends by name. Register all backends on the worker and reference each by name in the workflow:
+
+```python
+# Run a task on the "daytona" backend
+result = await Runner.run(
+    agent, prompt,
+    run_config=RunConfig(sandbox=SandboxRunConfig(
+        client=temporal_sandbox_client("daytona"),
+        options=DaytonaSandboxClientOptions(pause_on_exit=False),
+    )),
+)
+
+# Run a different task on the "local" backend
+result = await Runner.run(
+    agent, prompt,
+    run_config=RunConfig(sandbox=SandboxRunConfig(
+        client=temporal_sandbox_client("local"),
+        options=UnixLocalSandboxClientOptions(),
+    )),
+)
+```
+
 ## Feature Support
 
 This integration is presently subject to certain limitations.

temporalio/contrib/openai_agents/__init__.py

@@ -13,6 +13,9 @@
     OpenAIAgentsPlugin,
     OpenAIPayloadConverter,
 )
+from temporalio.contrib.openai_agents.sandbox._sandbox_client_provider import (
+    SandboxClientProvider,
+)
 from temporalio.contrib.openai_agents.workflow import AgentsWorkflowError
 
 from . import testing, workflow
@@ -22,6 +25,7 @@
     "ModelActivityParameters",
     "OpenAIAgentsPlugin",
     "OpenAIPayloadConverter",
+    "SandboxClientProvider",
     "StatelessMCPServerProvider",
     "StatefulMCPServerProvider",
     "testing",

temporalio/contrib/openai_agents/_invoke_model_activity.py

@@ -27,6 +27,13 @@
     UserError,
     WebSearchTool,
 )
+from agents.tool import (
+    ApplyPatchTool,
+    LocalShellTool,
+    ShellTool,
+    ShellToolEnvironment,
+    ToolSearchTool,
+)
 from openai import (
     APIStatusError,
     AsyncOpenAI,
@@ -73,13 +80,47 @@ class HostedMCPToolInput:
     tool_config: Mcp
 
 
+@dataclass
+class ShellToolInput:
+    """Data conversion friendly representation of a ShellTool. Contains only the fields which are needed by the model
+    execution to determine what tool to call, not the actual tool invocation, which remains in the workflow context.
+    """
+
+    name: str = "shell"
+    environment: ShellToolEnvironment | None = None
+
+
+class _NoopApplyPatchEditor:
+    """Satisfies the ApplyPatchEditor protocol for tool reconstruction during model calls."""
+
+    def create_file(self, operation: Any) -> None:  # type: ignore[reportUnusedParameter]
+        return None
+
+    def update_file(self, operation: Any) -> None:  # type: ignore[reportUnusedParameter]
+        return None
+
+    def delete_file(self, operation: Any) -> None:  # type: ignore[reportUnusedParameter]
+        return None
+
+
+@dataclass
+class ApplyPatchToolInput:
+    """Data conversion friendly representation of an ApplyPatchTool."""
+
+    name: str = "apply_patch"
+
+
 ToolInput = (
     FunctionToolInput
     | FileSearchTool
     | WebSearchTool
     | ImageGenerationTool
     | CodeInterpreterTool
     | HostedMCPToolInput
+    | ShellToolInput
+    | LocalShellTool
+    | ApplyPatchToolInput
+    | ToolSearchTool
 )
 
 
@@ -181,9 +222,26 @@ def make_tool(tool: ToolInput) -> Tool:
                     WebSearchTool,
                     ImageGenerationTool,
                     CodeInterpreterTool,
+                    LocalShellTool,
+                    ToolSearchTool,
                 ),
             ):
                 return tool
+            elif isinstance(tool, ShellToolInput):
+
+                async def _noop_executor(*a: Any, **kw: Any) -> str:  # type: ignore[reportUnusedParameter]
+                    return ""
+
+                return ShellTool(
+                    name=tool.name,
+                    environment=tool.environment,
+                    executor=_noop_executor,
+                )
+            elif isinstance(tool, ApplyPatchToolInput):
+                return ApplyPatchTool(
+                    name=tool.name,
+                    editor=_NoopApplyPatchEditor(),
+                )
             elif isinstance(tool, HostedMCPToolInput):
                 return HostedMCPTool(
                     tool_config=tool.tool_config,

temporalio/contrib/openai_agents/_mcp.py

@@ -41,6 +41,7 @@ class _StatelessCallToolsArguments:
     tool_name: str
     arguments: dict[str, Any] | None
     factory_argument: Any | None
+    meta: dict[str, Any] | None = None
 
 
 @dataclasses.dataclass
@@ -100,11 +101,16 @@ async def list_tools(
         return tools
 
     async def call_tool(
-        self, tool_name: str, arguments: dict[str, Any] | None
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None,
+        meta: dict[str, Any] | None = None,
     ) -> CallToolResult:
         return await workflow.execute_activity(
             self.name + "-call-tool-v2",
-            _StatelessCallToolsArguments(tool_name, arguments, self._factory_argument),
+            _StatelessCallToolsArguments(
+                tool_name, arguments, self._factory_argument, meta
+            ),
             result_type=CallToolResult,
             **self._config,
         )
@@ -190,7 +196,7 @@ async def call_tool(args: _StatelessCallToolsArguments) -> CallToolResult:
             server = self._create_server(args.factory_argument)
             try:
                 await server.connect()
-                return await server.call_tool(args.tool_name, args.arguments)
+                return await server.call_tool(args.tool_name, args.arguments, args.meta)
             finally:
                 await server.cleanup()
 
@@ -275,6 +281,7 @@ async def wrapper(*args: Any, **kwargs: Any):
 class _StatefulCallToolsArguments:
     tool_name: str
     arguments: dict[str, Any] | None
+    meta: dict[str, Any] | None = None
 
 
 @dataclasses.dataclass
@@ -362,15 +369,18 @@ async def list_tools(
 
     @_handle_worker_failure
     async def call_tool(
-        self, tool_name: str, arguments: dict[str, Any] | None
+        self,
+        tool_name: str,
+        arguments: dict[str, Any] | None,
+        meta: dict[str, Any] | None = None,
     ) -> CallToolResult:
         if not self._connect_handle:
             raise ApplicationError(
                 "Stateful MCP Server not connected. Call connect first."
             )
         return await workflow.execute_activity(
             self.name + "-call-tool-v2",
-            _StatefulCallToolsArguments(tool_name, arguments),
+            _StatefulCallToolsArguments(tool_name, arguments, meta),
             result_type=CallToolResult,
             **self._config,
         )
@@ -460,7 +470,7 @@ async def call_tool_deprecated(
         @activity.defn(name=self.name + "-call-tool-v2")
         async def call_tool(args: _StatefulCallToolsArguments) -> CallToolResult:
             return await self._servers[_server_id()].call_tool(
-                args.tool_name, args.arguments
+                args.tool_name, args.arguments, args.meta
             )
 
         @activity.defn(name=self.name + "-list-prompts")