runloopai · sid-rl · Dec 12, 2025 · Dec 6, 2025 · Dec 8, 2025 · Dec 9, 2025
diff --git a/README.md b/README.md
@@ -33,10 +33,10 @@ For a higher-level, Pythonic interface, check out the new [`RunloopSDK`](README-
 ```python
 from runloop_api_client import RunloopSDK
 
-sdk = RunloopSDK()  # Uses RUNLOOP_API_KEY environment variable by default
+runloop = RunloopSDK()  # Uses RUNLOOP_API_KEY environment variable by default
 
 # Create a devbox and execute commands with a clean, object-oriented interface
-with sdk.devbox.create(name="my-devbox") as devbox:
+with runloop.devbox.create(name="my-devbox") as devbox:
     result = devbox.cmd.exec("echo 'Hello from Runloop!'")
     print(result.stdout())
 ```

diff --git a/src/runloop_api_client/sdk/__init__.py b/src/runloop_api_client/sdk/__init__.py
@@ -7,6 +7,7 @@
 
 from .sync import AgentOps, DevboxOps, ScorerOps, RunloopSDK, ScenarioOps, SnapshotOps, BlueprintOps, StorageObjectOps
 from .agent import Agent
+from ._types import ScenarioPreview
 from .async_ import (
     AsyncAgentOps,
     AsyncDevboxOps,
@@ -33,9 +34,11 @@
 from .async_blueprint import AsyncBlueprint
 from .async_execution import AsyncExecution
 from .execution_result import ExecutionResult
+from .scenario_builder import ScenarioBuilder
 from .async_scenario_run import AsyncScenarioRun
 from .async_storage_object import AsyncStorageObject
 from .async_execution_result import AsyncExecutionResult
+from .async_scenario_builder import AsyncScenarioBuilder
 
 __all__ = [
     # Main SDK entry points
@@ -71,6 +74,9 @@
     "AsyncScenario",
     "ScenarioRun",
     "AsyncScenarioRun",
+    "ScenarioBuilder",
+    "AsyncScenarioBuilder",
+    "ScenarioPreview",
     "Scorer",
     "AsyncScorer",
     "Snapshot",

diff --git a/src/runloop_api_client/sdk/_types.py b/src/runloop_api_client/sdk/_types.py
@@ -5,6 +5,8 @@
 from ..lib.polling import PollingConfig
 from ..types.devboxes import DiskSnapshotListParams, DiskSnapshotUpdateParams
 from ..types.scenarios import ScorerListParams, ScorerCreateParams, ScorerUpdateParams, ScorerValidateParams
+from ..types.input_context import InputContext
+from ..types.scenario_view import ScenarioView
 from ..types.agent_list_params import AgentListParams
 from ..types.devbox_list_params import DevboxListParams
 from ..types.object_list_params import ObjectListParams
@@ -186,3 +188,18 @@ class SDKScenarioRunAsyncParams(ScenarioStartRunBaseParams, LongRequestOptions):
 
 class SDKScenarioRunParams(ScenarioStartRunBaseParams, LongPollingRequestOptions):
     pass
+
+
+class InputContextPreview(InputContext):
+    problem_statement: Optional[str] = None  # type: ignore[assignment]
+    """The problem statement for the Scenario."""
+
+
+class ScenarioPreview(ScenarioView):
+    """Preview of scenario configuration with all fields optional."""
+
+    id: Optional[str] = None  # type: ignore[assignment]
+    """The ID of the Scenario."""
+
+    input_context: InputContextPreview  # type: ignore[assignment]
+    """The input context for the Scenario."""
diff --git a/src/runloop_api_client/sdk/async_.py b/src/runloop_api_client/sdk/async_.py
@@ -37,6 +37,7 @@
 from .async_blueprint import AsyncBlueprint
 from ..lib.context_loader import TarFilter, build_directory_tar
 from .async_storage_object import AsyncStorageObject
+from .async_scenario_builder import AsyncScenarioBuilder
 from ..types.object_create_params import ContentType
 from ..types.shared_params.agent_source import Git, Npm, Pip, Object
 
@@ -773,6 +774,16 @@ class AsyncScenarioOps:
         >>> scenario = runloop.scenario.from_id("scn-xxx")
         >>> run = await scenario.run()
         >>> scenarios = await runloop.scenario.list()
+
+    Example using builder:
+        >>> builder = (
+        ...     runloop.scenario.builder("my-scenario")
+        ...     .from_blueprint(blueprint)
+        ...     .with_problem_statement("Fix the bug")
+        ...     .add_test_command_scorer("tests", test_command="pytest")
+        ... )
+        >>> params = builder.build()
+        >>> scenario = await runloop.scenario.create(**params)  # equivalent to builder.push()
     """
 
     def __init__(self, client: AsyncRunloop) -> None:
@@ -783,6 +794,16 @@ def __init__(self, client: AsyncRunloop) -> None:
         """
         self._client = client
 
+    def builder(self, name: str) -> AsyncScenarioBuilder:
+        """Create a new scenario builder.
+
+        :param name: Name for the scenario
+        :type name: str
+        :return: A new AsyncScenarioBuilder instance
+        :rtype: AsyncScenarioBuilder
+        """
+        return AsyncScenarioBuilder(name, self._client)
+
     def from_id(self, scenario_id: str) -> AsyncScenario:
         """Get an AsyncScenario instance for an existing scenario ID.