feat: [APP-3106] Specs: Explicit QueryMode for cloud agent run creation

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 22
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta/warp-api-8eb8e46de29b887cbcb25b90fec55d34e11ff82b174b7a5c1d1ce4ba4d7c2fb4.yml
-openapi_spec_hash: a071b7c932453dc870e7e6cf39df0535
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/warp-bnavetta/warp-api-f4c3bab952ad19ea9d246794add1bda6d3911eb32d8372f0d7271b52267b6d0b.yml
+openapi_spec_hash: 9fd38bfc2e640fb456258f50fccacf88
 config_hash: c15534df6c8d861059e44d9dd5483b3f

src/oz_agent_sdk/resources/agent/agent.py

@@ -262,6 +262,7 @@ def run(
         config: AmbientAgentConfigParam | Omit = omit,
         conversation_id: str | Omit = omit,
         interactive: bool | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         parent_run_id: str | Omit = omit,
         prompt: str | Omit = omit,
         skill: str | Omit = omit,
@@ -293,6 +294,10 @@ def run(
 
           interactive: Whether the run should be interactive. If not set, defaults to false.
 
+          mode: Optional query mode for the run. Defaults to `normal` when omitted. The server
+              does not infer mode from prompt prefixes such as `/plan`, so callers should pass
+              this field explicitly to request non-normal behavior.
+
           parent_run_id: Optional run ID of the parent that spawned this run. Used for orchestration
               hierarchies.
 
@@ -329,6 +334,7 @@ def run(
                     "config": config,
                     "conversation_id": conversation_id,
                     "interactive": interactive,
+                    "mode": mode,
                     "parent_run_id": parent_run_id,
                     "prompt": prompt,
                     "skill": skill,
@@ -547,6 +553,7 @@ async def run(
         config: AmbientAgentConfigParam | Omit = omit,
         conversation_id: str | Omit = omit,
         interactive: bool | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         parent_run_id: str | Omit = omit,
         prompt: str | Omit = omit,
         skill: str | Omit = omit,
@@ -578,6 +585,10 @@ async def run(
 
           interactive: Whether the run should be interactive. If not set, defaults to false.
 
+          mode: Optional query mode for the run. Defaults to `normal` when omitted. The server
+              does not infer mode from prompt prefixes such as `/plan`, so callers should pass
+              this field explicitly to request non-normal behavior.
+
           parent_run_id: Optional run ID of the parent that spawned this run. Used for orchestration
               hierarchies.
 
@@ -614,6 +625,7 @@ async def run(
                     "config": config,
                     "conversation_id": conversation_id,
                     "interactive": interactive,
+                    "mode": mode,
                     "parent_run_id": parent_run_id,
                     "prompt": prompt,
                     "skill": skill,

src/oz_agent_sdk/resources/agent/runs.py

@@ -302,6 +302,7 @@ def submit_followup(
         run_id: str,
         *,
         message: str,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -319,6 +320,9 @@ def submit_followup(
         Args:
           message: The follow-up message to send to the run.
 
+          mode: Optional query mode for the follow-up. Defaults to `normal` when omitted. The
+              server does not infer mode from prompt prefixes such as `/plan`.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -331,7 +335,13 @@ def submit_followup(
             raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}")
         return self._post(
             path_template("/agent/runs/{run_id}/followups", run_id=run_id),
-            body=maybe_transform({"message": message}, run_submit_followup_params.RunSubmitFollowupParams),
+            body=maybe_transform(
+                {
+                    "message": message,
+                    "mode": mode,
+                },
+                run_submit_followup_params.RunSubmitFollowupParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -612,6 +622,7 @@ async def submit_followup(
         run_id: str,
         *,
         message: str,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -629,6 +640,9 @@ async def submit_followup(
         Args:
           message: The follow-up message to send to the run.
 
+          mode: Optional query mode for the follow-up. Defaults to `normal` when omitted. The
+              server does not infer mode from prompt prefixes such as `/plan`.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -641,7 +655,13 @@ async def submit_followup(
             raise ValueError(f"Expected a non-empty value for `run_id` but received {run_id!r}")
         return await self._post(
             path_template("/agent/runs/{run_id}/followups", run_id=run_id),
-            body=await async_maybe_transform({"message": message}, run_submit_followup_params.RunSubmitFollowupParams),
+            body=await async_maybe_transform(
+                {
+                    "message": message,
+                    "mode": mode,
+                },
+                run_submit_followup_params.RunSubmitFollowupParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),

src/oz_agent_sdk/resources/agent/schedules.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing_extensions import Literal
+
 import httpx
 
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
@@ -54,6 +56,7 @@ def create(
         agent_config: AmbientAgentConfigParam | Omit = omit,
         agent_uid: str | Omit = omit,
         enabled: bool | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         prompt: str | Omit = omit,
         team: bool | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -81,6 +84,9 @@ def create(
 
           enabled: Whether the schedule should be active immediately
 
+          mode: Optional query mode applied to every triggered run. Defaults to `normal` when
+              omitted. The server does not infer mode from prompt prefixes such as `/plan`.
+
           prompt: The prompt/instruction for the agent to execute. Required unless
               agent_config.skill_spec is provided.
 
@@ -104,6 +110,7 @@ def create(
                     "agent_config": agent_config,
                     "agent_uid": agent_uid,
                     "enabled": enabled,
+                    "mode": mode,
                     "prompt": prompt,
                     "team": team,
                 },
@@ -158,6 +165,7 @@ def update(
         name: str,
         agent_config: AmbientAgentConfigParam | Omit = omit,
         agent_uid: str | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         prompt: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -183,6 +191,9 @@ def update(
           agent_uid: Agent UID to use as the execution principal for this schedule. Only valid for
               team-owned schedules.
 
+          mode: Optional query mode applied to every triggered run. Defaults to `normal` when
+              omitted. The server does not infer mode from prompt prefixes such as `/plan`.
+
           prompt: The prompt/instruction for the agent to execute. Required unless
               agent_config.skill_spec is provided.
 
@@ -205,6 +216,7 @@ def update(
                     "name": name,
                     "agent_config": agent_config,
                     "agent_uid": agent_uid,
+                    "mode": mode,
                     "prompt": prompt,
                 },
                 schedule_update_params.ScheduleUpdateParams,
@@ -372,6 +384,7 @@ async def create(
         agent_config: AmbientAgentConfigParam | Omit = omit,
         agent_uid: str | Omit = omit,
         enabled: bool | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         prompt: str | Omit = omit,
         team: bool | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -399,6 +412,9 @@ async def create(
 
           enabled: Whether the schedule should be active immediately
 
+          mode: Optional query mode applied to every triggered run. Defaults to `normal` when
+              omitted. The server does not infer mode from prompt prefixes such as `/plan`.
+
           prompt: The prompt/instruction for the agent to execute. Required unless
               agent_config.skill_spec is provided.
 
@@ -422,6 +438,7 @@ async def create(
                     "agent_config": agent_config,
                     "agent_uid": agent_uid,
                     "enabled": enabled,
+                    "mode": mode,
                     "prompt": prompt,
                     "team": team,
                 },
@@ -476,6 +493,7 @@ async def update(
         name: str,
         agent_config: AmbientAgentConfigParam | Omit = omit,
         agent_uid: str | Omit = omit,
+        mode: Literal["normal", "plan", "orchestrate"] | Omit = omit,
         prompt: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -501,6 +519,9 @@ async def update(
           agent_uid: Agent UID to use as the execution principal for this schedule. Only valid for
               team-owned schedules.
 
+          mode: Optional query mode applied to every triggered run. Defaults to `normal` when
+              omitted. The server does not infer mode from prompt prefixes such as `/plan`.
+
           prompt: The prompt/instruction for the agent to execute. Required unless
               agent_config.skill_spec is provided.
 
@@ -523,6 +544,7 @@ async def update(
                     "name": name,
                     "agent_config": agent_config,
                     "agent_uid": agent_uid,
+                    "mode": mode,
                     "prompt": prompt,
                 },
                 schedule_update_params.ScheduleUpdateParams,

src/oz_agent_sdk/types/agent/run_submit_followup_params.py

@@ -2,11 +2,18 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 __all__ = ["RunSubmitFollowupParams"]
 
 
 class RunSubmitFollowupParams(TypedDict, total=False):
     message: Required[str]
     """The follow-up message to send to the run."""
+
+    mode: Literal["normal", "plan", "orchestrate"]
+    """Optional query mode for the follow-up.
+
+    Defaults to `normal` when omitted. The server does not infer mode from prompt
+    prefixes such as `/plan`.
+    """

src/oz_agent_sdk/types/agent/schedule_create_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 from ..ambient_agent_config_param import AmbientAgentConfigParam
 
@@ -31,6 +31,13 @@ class ScheduleCreateParams(TypedDict, total=False):
     enabled: bool
     """Whether the schedule should be active immediately"""
 
+    mode: Literal["normal", "plan", "orchestrate"]
+    """Optional query mode applied to every triggered run.
+
+    Defaults to `normal` when omitted. The server does not infer mode from prompt
+    prefixes such as `/plan`.
+    """
+
     prompt: str
     """
     The prompt/instruction for the agent to execute. Required unless

src/oz_agent_sdk/types/agent/schedule_update_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 from ..ambient_agent_config_param import AmbientAgentConfigParam
 
@@ -28,6 +28,13 @@ class ScheduleUpdateParams(TypedDict, total=False):
     team-owned schedules.
     """
 
+    mode: Literal["normal", "plan", "orchestrate"]
+    """Optional query mode applied to every triggered run.
+
+    Defaults to `normal` when omitted. The server does not infer mode from prompt
+    prefixes such as `/plan`.
+    """
+
     prompt: str
     """
     The prompt/instruction for the agent to execute. Required unless

src/oz_agent_sdk/types/agent_run_params.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Union, Iterable
-from typing_extensions import Required, Annotated, TypedDict
+from typing_extensions import Literal, Required, Annotated, TypedDict
 
 from .._types import Base64FileInput
 from .._utils import PropertyInfo
@@ -38,6 +38,14 @@ class AgentRunParams(TypedDict, total=False):
     interactive: bool
     """Whether the run should be interactive. If not set, defaults to false."""
 
+    mode: Literal["normal", "plan", "orchestrate"]
+    """Optional query mode for the run.
+
+    Defaults to `normal` when omitted. The server does not infer mode from prompt
+    prefixes such as `/plan`, so callers should pass this field explicitly to
+    request non-normal behavior.
+    """
+
     parent_run_id: str
     """
     Optional run ID of the parent that spawned this run. Used for orchestration

tests/api_resources/agent/test_runs.py

@@ -213,6 +213,16 @@ def test_method_submit_followup(self, client: OzAPI) -> None:
         )
         assert_matches_type(object, run, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_submit_followup_with_all_params(self, client: OzAPI) -> None:
+        run = client.agent.runs.submit_followup(
+            run_id="runId",
+            message="message",
+            mode="normal",
+        )
+        assert_matches_type(object, run, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     def test_raw_response_submit_followup(self, client: OzAPI) -> None:
@@ -447,6 +457,16 @@ async def test_method_submit_followup(self, async_client: AsyncOzAPI) -> None:
         )
         assert_matches_type(object, run, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_submit_followup_with_all_params(self, async_client: AsyncOzAPI) -> None:
+        run = await async_client.agent.runs.submit_followup(
+            run_id="runId",
+            message="message",
+            mode="normal",
+        )
+        assert_matches_type(object, run, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     async def test_raw_response_submit_followup(self, async_client: AsyncOzAPI) -> None:

tests/api_resources/agent/test_schedules.py

@@ -61,6 +61,7 @@ def test_method_create_with_all_params(self, client: OzAPI) -> None:
             },
             agent_uid="agent_uid",
             enabled=True,
+            mode="normal",
             prompt="Review open pull requests and provide feedback",
             team=True,
         )
@@ -179,6 +180,7 @@ def test_method_update_with_all_params(self, client: OzAPI) -> None:
                 "worker_host": "worker_host",
             },
             agent_uid="agent_uid",
+            mode="normal",
             prompt="prompt",
         )
         assert_matches_type(ScheduledAgentItem, schedule, path=["response"])
@@ -426,6 +428,7 @@ async def test_method_create_with_all_params(self, async_client: AsyncOzAPI) ->
             },
             agent_uid="agent_uid",
             enabled=True,
+            mode="normal",
             prompt="Review open pull requests and provide feedback",
             team=True,
         )
@@ -544,6 +547,7 @@ async def test_method_update_with_all_params(self, async_client: AsyncOzAPI) ->
                 "worker_host": "worker_host",
             },
             agent_uid="agent_uid",
+            mode="normal",
             prompt="prompt",
         )
         assert_matches_type(ScheduledAgentItem, schedule, path=["response"])