Added session create helper

Author: monadoid

README.md

@@ -35,43 +35,32 @@ python examples/full_example.py
 This example demonstrates the full Stagehand workflow: starting a session, navigating to a page, observing possible actions, acting on elements, extracting data, and running an autonomous agent.
 
 ```python
-from stagehand import Stagehand, __version__
+from stagehand import Stagehand
 
 
 def main() -> None:
-    sdk_version = __version__
-
     # Create client using environment variables:
     # BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, MODEL_API_KEY
     client = Stagehand()
 
-    # Start a new browser session
-    start_response = client.sessions.start(
+    # Start a new browser session (returns a session helper bound to a session_id)
+    session = client.sessions.create(
         model_name="openai/gpt-5-nano",
-        x_language="python",
-        x_sdk_version=sdk_version,
     )
 
-    session_id = start_response.data.session_id
-    print(f"Session started: {session_id}")
+    print(f"Session started: {session.id}")
 
     try:
         # Navigate to a webpage
-        client.sessions.navigate(
-            id=session_id,
+        session.navigate(
             url="https://news.ycombinator.com",
             frame_id="",  # empty string for the main frame
-            x_language="python",
-            x_sdk_version=sdk_version,
         )
         print("Navigated to Hacker News")
 
         # Observe to find possible actions on the page
-        observe_response = client.sessions.observe(
-            id=session_id,
+        observe_response = session.observe(
             instruction="find the link to view comments for the top post",
-            x_language="python",
-            x_sdk_version=sdk_version,
         )
 
         results = observe_response.data.result
@@ -83,17 +72,13 @@ def main() -> None:
         action = results[0].to_dict(exclude_none=True)
         print("Acting on:", action.get("description"))
 
-        act_response = client.sessions.act(
-            id=session_id,
+        act_response = session.act(
             input=action,
-            x_language="python",
-            x_sdk_version=sdk_version,
         )
         print("Act completed:", act_response.data.result.message)
 
         # Extract structured data from the page using a JSON schema
-        extract_response = client.sessions.extract(
-            id=session_id,
+        extract_response = session.extract(
             instruction="extract the text of the top comment on this page",
             schema={
                 "type": "object",
@@ -103,32 +88,27 @@ def main() -> None:
                 },
                 "required": ["commentText"],
             },
-            x_language="python",
-            x_sdk_version=sdk_version,
         )
 
         extracted = extract_response.data.result
         author = extracted.get("author", "unknown") if isinstance(extracted, dict) else "unknown"
         print("Extracted author:", author)
 
         # Run an autonomous agent to accomplish a complex task
-        execute_response = client.sessions.execute(
-            id=session_id,
+        execute_response = session.execute(
             execute_options={
                 "instruction": f"Find any personal website, GitHub, or LinkedIn profile for the Hacker News user '{author}'.",
                 "max_steps": 10,
             },
             agent_config={"model": "openai/gpt-5-nano"},
-            x_language="python",
-            x_sdk_version=sdk_version,
             timeout=300.0,
         )
 
         print("Agent completed:", execute_response.data.result.message)
         print("Agent success:", execute_response.data.result.success)
     finally:
         # End the browser session to clean up resources
-        client.sessions.end(id=session_id, x_language="python", x_sdk_version=sdk_version)
+        session.end()
         print("Session ended")
 
 

examples/act_example.py

@@ -29,17 +29,15 @@ def main() -> None:
     )
 
     # Start a new browser session
-    start_response = client.sessions.start(
+    session = client.sessions.create(
         model_name="openai/gpt-5-nano",
     )
 
-    session_id = start_response.data.session_id
-    print(f"Session started: {session_id}")
+    print(f"Session started: {session.id}")
 
     try:
         # Navigate to example.com
-        client.sessions.navigate(
-            id=session_id,
+        session.navigate(
             url="https://www.example.com",
             frame_id="",  # Empty string for main frame
         )
@@ -48,8 +46,7 @@ def main() -> None:
         # Call act() with a string instruction directly
         # This is the key test - passing a string instead of an Action object
         print("\nAttempting to call act() with string input...")
-        act_response = client.sessions.act(
-            id=session_id,
+        act_response = session.act(
             input="click the 'More information' link",  # String instruction
         )
 
@@ -61,13 +58,12 @@ def main() -> None:
         print(f"Error: {e}")
         print(f"Error type: {type(e).__name__}")
         import traceback
+
         traceback.print_exc()
 
     finally:
         # End the session to clean up resources
-        client.sessions.end(
-            id=session_id,
-        )
+        session.end()
         print("\nSession ended")
 
 

examples/agent_execute.py

@@ -27,7 +27,7 @@ def main() -> None:
     # with missing fields set to None).
     with Stagehand(_strict_response_validation=True) as client:
         try:
-            session = client.sessions.start(model_name=model_name)
+            session = client.sessions.create(model_name=model_name)
         except APIResponseValidationError as e:
             print("Session start response failed schema validation.")
             print(f"Base URL: {client.base_url!r}")
@@ -37,19 +37,16 @@ def main() -> None:
             print("Parsed response body:")
             print(e.body)
             raise
-        session_id = session.data.session_id
-        if not session_id:
-            raise RuntimeError(f"Expected a session ID from /sessions/start but received {session.to_dict()!r}")
+        if not session.id:
+            raise RuntimeError(f"Expected a session ID from /sessions/start but received {session!r}")
 
         try:
-            client.sessions.navigate(
-                id=session_id,
+            session.navigate(
                 url="https://news.ycombinator.com",
                 options={"wait_until": "domcontentloaded"},
             )
 
-            result = client.sessions.execute(
-                id=session_id,
+            result = session.execute(
                 agent_config={"model": model_name},
                 execute_options={
                     "instruction": "Go to Hacker News and return the titles of the first 3 articles.",
@@ -61,9 +58,7 @@ def main() -> None:
             print("\nFull result:")
             print(json.dumps(result.data.result.to_dict(), indent=2, default=str))
         finally:
-            # Only attempt cleanup if a valid session ID was created.
-            if session_id:
-                client.sessions.end(id=session_id)
+            session.end()
 
 
 if __name__ == "__main__":

examples/full_example.py

@@ -30,26 +30,23 @@ def main() -> None:
         model_api_key=os.environ.get("MODEL_API_KEY"),
     )
 
-    # Start a new browser session
-    start_response = client.sessions.start(
+    # Start a new browser session (returns a session helper bound to a session_id)
+    session = client.sessions.create(
         model_name="openai/gpt-5-nano",
     )
 
-    session_id = start_response.data.session_id
-    print(f"Session started: {session_id}")
+    print(f"Session started: {session.id}")
 
     try:
         # Navigate to Hacker News
-        client.sessions.navigate(
-            id=session_id,
+        session.navigate(
             url="https://news.ycombinator.com",
             frame_id="",  # Empty string for main frame
         )
         print("Navigated to Hacker News")
 
         # Observe to find possible actions - looking for the comments link
-        observe_response = client.sessions.observe(
-            id=session_id,
+        observe_response = session.observe(
             instruction="find the link to view comments for the top post",
         )
 
@@ -65,30 +62,22 @@ def main() -> None:
         print(f"Acting on: {result.description}")
 
         # Pass the action to Act
-        act_response = client.sessions.act(
-            id=session_id,
+        act_response = session.act(
             input=result,  # type: ignore[arg-type]
         )
         print(f"Act completed: {act_response.data.result.message}")
 
         # Extract data from the page
         # We're now on the comments page, so extract the top comment text
-        extract_response = client.sessions.extract(
-            id=session_id,
+        extract_response = session.extract(
             instruction="extract the text of the top comment on this page",
             schema={
                 "type": "object",
                 "properties": {
-                    "commentText": {
-                        "type": "string",
-                        "description": "The text content of the top comment"
-                    },
-                    "author": {
-                        "type": "string",
-                        "description": "The username of the comment author"
-                    }
+                    "commentText": {"type": "string", "description": "The text content of the top comment"},
+                    "author": {"type": "string", "description": "The username of the comment author"},
                 },
-                "required": ["commentText"]
+                "required": ["commentText"],
             },
         )
 
@@ -103,8 +92,7 @@ def main() -> None:
         # Use the Agent to find the author's profile
         # Execute runs an autonomous agent that can navigate and interact with pages
         # Use a longer timeout (5 minutes) since agent execution can take a while
-        execute_response = client.sessions.execute(  # pyright: ignore[reportArgumentType]
-            id=session_id,
+        execute_response = session.execute(  # pyright: ignore[reportArgumentType]
             execute_options={
                 "instruction": (
                     f"Find any personal website, GitHub, LinkedIn, or other best profile URL for the Hacker News user '{author}'. "
@@ -129,9 +117,7 @@ def main() -> None:
 
     finally:
         # End the session to clean up resources
-        client.sessions.end(
-            id=session_id,
-        )
+        session.end()
         print("Session ended")
 
 

src/stagehand/_client.py

@@ -34,7 +34,7 @@
 
 if TYPE_CHECKING:
     from .resources import sessions
-    from .resources.sessions import SessionsResource, AsyncSessionsResource
+    from .resources.sessions_helpers import SessionsResourceWithHelpers, AsyncSessionsResourceWithHelpers
 
 __all__ = [
     "Timeout",
@@ -179,10 +179,10 @@ def close(self) -> None:
                 self._sea_server.close()
 
     @cached_property
-    def sessions(self) -> SessionsResource:
-        from .resources.sessions import SessionsResource
+    def sessions(self) -> SessionsResourceWithHelpers:
+        from .resources.sessions_helpers import SessionsResourceWithHelpers
 
-        return SessionsResource(self)
+        return SessionsResourceWithHelpers(self)
 
     @cached_property
     def with_raw_response(self) -> StagehandWithRawResponse:
@@ -469,10 +469,10 @@ async def close(self) -> None:
                 await self._sea_server.aclose()
 
     @cached_property
-    def sessions(self) -> AsyncSessionsResource:
-        from .resources.sessions import AsyncSessionsResource
+    def sessions(self) -> AsyncSessionsResourceWithHelpers:
+        from .resources.sessions_helpers import AsyncSessionsResourceWithHelpers
 
-        return AsyncSessionsResource(self)
+        return AsyncSessionsResourceWithHelpers(self)
 
     @cached_property
     def with_raw_response(self) -> AsyncStagehandWithRawResponse: