docs: add Settings and Secrets API guide

docs.json

@@ -269,6 +269,7 @@
                   "sdk/guides/agent-server/api-sandbox",
                   "sdk/guides/agent-server/cloud-workspace",
                   "sdk/guides/agent-server/custom-tools",
+                  "sdk/guides/agent-server/settings-secrets-api",
                   {
                     "group": "API Reference",
                     "openapi": {

sdk/guides/agent-server/settings-secrets-api.mdx

@@ -0,0 +1,119 @@
+---
+title: Settings and Secrets API
+description: Manage agent settings and custom secrets through the agent server REST API.
+---
+
+import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx";
+
+> A ready-to-run example is available [here](#ready-to-run-example)!
+
+The Settings and Secrets API provides REST endpoints for managing agent configuration and custom secrets through a local agent server. This is useful for:
+
+- Persisting agent settings across sessions
+- Managing custom secrets (API keys, tokens, credentials)
+- Integrating with frontend applications that need settings management
+
+## Key Concepts
+
+### Settings Endpoints
+
+The agent server exposes settings management via REST:
+
+- **GET /api/settings** - Retrieve current settings
+- **PATCH /api/settings** - Update settings with a partial diff
+
+```python icon="python"
+# Get current settings
+response = client.get("/api/settings")
+settings = response.json()
+
+# Update LLM model
+response = client.patch(
+    "/api/settings",
+    json={"agent_settings_diff": {"llm": {"model": "gpt-4o-mini"}}},
+)
+```
+
+### Secrets CRUD Operations
+
+Custom secrets can be created, listed, retrieved, and deleted:
+
+```python icon="python"
+# Create a secret
+client.put(
+    "/api/settings/secrets",
+    json={
+        "name": "MY_API_KEY",
+        "value": "sk-example-key-12345",
+        "description": "Example API key",
+    },
+)
+
+# List secrets (values not exposed)
+secrets = client.get("/api/settings/secrets").json()["secrets"]
+
+# Get secret value
+value = client.get("/api/settings/secrets/MY_API_KEY").text
+
+# Delete secret
+client.delete("/api/settings/secrets/MY_API_KEY")
+```
+
+### Secret Name Validation
+
+Secret names must follow environment variable naming conventions:
+
+- Start with a letter (a-z, A-Z)
+- Contain only letters, numbers, and underscores
+- Be 1-64 characters long
+
+Invalid names are rejected with a 422 response:
+
+```python icon="python"
+# Invalid: starts with number
+response = client.put(
+    "/api/settings/secrets",
+    json={"name": "123_invalid", "value": "test"},
+)
+assert response.status_code == 422
+
+# Invalid: contains hyphen
+response = client.put(
+    "/api/settings/secrets",
+    json={"name": "invalid-name", "value": "test"},
+)
+assert response.status_code == 422
+```
+
+### Secret Redaction
+
+When retrieving settings, secrets are redacted by default to prevent accidental exposure:
+
+```python icon="python"
+# Update LLM API key
+client.patch(
+    "/api/settings",
+    json={"agent_settings_diff": {"llm": {"api_key": "sk-live-test-key"}}},
+)
+
+# Get settings - key is redacted
+response = client.get("/api/settings")
+assert response.json()["agent_settings"]["llm"]["api_key"] == "**********"
+assert response.json()["llm_api_key_is_set"] is True
+```
+
+## Ready-to-Run Example
+
+This example starts a local agent server and exercises the full settings and secrets API:
+
+```python icon="python" expandable examples/02_remote_agent_server/12_settings_and_secrets_api.py
+<code will be auto-synced>
+```
+
+<RunExampleCode path_to_script="examples/02_remote_agent_server/12_settings_and_secrets_api.py"/>
+
+## Next Steps
+
+- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Run agents through a local HTTP server
+- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run server in Docker for isolation
+- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details