Merge branch 'main' into james/ctxt-loader

Author: james-rl

CONTRIBUTING.md

@@ -89,13 +89,49 @@ Most tests require you to [set up a mock server](https://github.com/stoplightio/
 
 ```sh
 # you will need npm installed
-$ npx prism mock path/to/your/openapi.yml
+npx prism mock path/to/your/openapi.yml
 ```
 
 ```sh
-$ ./scripts/test
+# run all tests
+./scripts/test
+
+# pass in pytest args, eg to show info on skipped tests:
+./scripts/test -rs
+
+# Run tests for only one python version
+UV_PYTHON=3.13 ./scripts/test
+```
+
+### Running pytets
+
+Assuming you have a uv virtual env set up in .venv, the following are helpful for more granular test running:
+
+```sh
+# Run all tests pytests
+.venv/bin/pytest tests/
+
+# Run all SDK tests with verbose info
+.venv/bin/pytest tests/sdk/ -v
+
+# Run specific test class
+.venv/bin/pytest tests/sdk/test_clients.py::TestAgentClient -v
+
+# Run specific test method
+.venv/bin/pytest tests/sdk/test_clients.py::TestAgentClient::test_create_from_npm -v
+
+# Run agent smoketests (requires RUNLOOP_API_KEY)
+export RUNLOOP_API_KEY=your_key_here
+.venv/bin/pytest tests/smoketests/sdk/test_agent.py -v
+
+# Run tests matching a pattern
+.venv/bin/pytest tests/sdk/ -k "agent" -v
+
+# Run with coverage
+.venv/bin/pytest tests/sdk/ --cov=src/runloop_api_client/sdk --cov-report=html
 ```
 
+
 ## Linting and formatting
 
 This repository uses [ruff](https://github.com/astral-sh/ruff) and

docs/Makefile

@@ -1,5 +1,11 @@
 # Minimal makefile for Sphinx documentation
 #
+# To rebuild the html docs, first make sure you've got the right deps installed via
+#    uv sync --group docs
+# then from the docs directory (this dir) rebuild with
+#    uv run make html
+# Look for generated docs under _build/html.
+
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.

docs/conf.py

@@ -35,7 +35,25 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
+
+# Furo theme options
+html_theme_options = {
+    "navigation_with_keys": True,
+    "sidebar_hide_name": False,
+}
+
+# Show the global toctree in sidebar
+html_sidebars = {
+    "**": [
+        "sidebar/scroll-start.html",
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/navigation.html",
+        "sidebar/ethical-ads.html",
+        "sidebar/scroll-end.html",
+    ]
+}
 
 # -- Extension configuration -------------------------------------------------
 

docs/sdk/async/agent.rst

@@ -0,0 +1,7 @@
+Agent
+======
+
+The ``AsyncAgent`` class provides asynchronous methods for managing and interacting with stored Agents.
+
+.. automodule:: runloop_api_client.sdk.async_agent
+   :members:

docs/sdk/async/index.rst

@@ -27,4 +27,4 @@ Asynchronous resource classes for working with devboxes, blueprints, snapshots,
    snapshot
    storage_object
    scorer
-
+   agent

docs/sdk/index.rst

@@ -9,6 +9,6 @@ The Runloop SDK provides both synchronous and asynchronous interfaces for managi
    :maxdepth: 2
    :caption: SDK Documentation
 
-   sync/index
    async/index
+   sync/index
    types

docs/sdk/sync/agent.rst

@@ -0,0 +1,7 @@
+Agent
+======
+
+The ``Agent`` class provides synchronous methods for managing and interacting with stored Agents.
+
+.. automodule:: runloop_api_client.sdk.agent
+   :members:

docs/sdk/sync/index.rst

@@ -27,4 +27,5 @@ Synchronous resource classes for working with devboxes, blueprints, snapshots, a
    snapshot
    storage_object
    scorer
+   agent
 

scripts/lint

@@ -5,7 +5,7 @@ set -e
 cd "$(dirname "$0")/.."
 
 echo "==> Running lints"
-uv run ruff check .
+uv run ruff check . "$@"
 
 echo "==> Making sure it imports"
 uv run python -c 'import runloop_api_client'

src/runloop_api_client/sdk/__init__.py

@@ -5,8 +5,10 @@
 
 from __future__ import annotations
 
-from .sync import DevboxOps, ScorerOps, RunloopSDK, SnapshotOps, BlueprintOps, StorageObjectOps
+from .sync import AgentOps, DevboxOps, ScorerOps, RunloopSDK, SnapshotOps, BlueprintOps, StorageObjectOps
+from .agent import Agent
 from .async_ import (
+    AsyncAgentOps,
     AsyncDevboxOps,
     AsyncScorerOps,
     AsyncRunloopSDK,
@@ -19,6 +21,7 @@
 from .snapshot import Snapshot
 from .blueprint import Blueprint
 from .execution import Execution
+from .async_agent import AsyncAgent
 from .async_devbox import AsyncDevbox, AsyncNamedShell
 from .async_scorer import AsyncScorer
 from .async_snapshot import AsyncSnapshot
@@ -34,6 +37,8 @@
     "RunloopSDK",
     "AsyncRunloopSDK",
     # Management interfaces
+    "AgentOps",
+    "AsyncAgentOps",
     "DevboxOps",
     "AsyncDevboxOps",
     "BlueprintOps",
@@ -45,6 +50,8 @@
     "StorageObjectOps",
     "AsyncStorageObjectOps",
     # Resource classes
+    "Agent",
+    "AsyncAgent",
     "Devbox",
     "AsyncDevbox",
     "Execution",