diff --git a/sdk/guides/llm-profiles.mdx b/sdk/guides/llm-profiles.mdx
new file mode 100644
index 00000000..58cfcfe1
--- /dev/null
+++ b/sdk/guides/llm-profiles.mdx
@@ -0,0 +1,37 @@
+---
+title: LLM Profiles
+description: Persist LLM configurations on disk and reference them from conversation state.
+---
+
+<Note>
+This example is available on GitHub: [examples/01_standalone_sdk/35_llm_profiles.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/35_llm_profiles.py)
+</Note>
+
+LLM profiles are full LLM configurations stored as JSON files. They are provider-neutral: a profile can include any LLM fields that matter for your provider (e.g., `model`, `base_url`, `temperature`, etc.).
+
+Profiles are stored under:
+
+- `$LLM_PROFILES_DIR/<profile_id>.json` when `LLM_PROFILES_DIR` is set
+- `~/.openhands/llm-profiles/<profile_id>.json` otherwise
+
+## Security note
+
+By default, `LLMRegistry.save_profile(..., include_secrets=True)` writes secret fields (like API keys) to disk.
+
+If you want keyless profiles, save profiles with `include_secrets=False` and provide secrets at runtime via env vars.
+
+## Example
+
+```python icon="python" expandable examples/01_standalone_sdk/35_llm_profiles.py
+# code will be auto-synced from agent-sdk
+```
+
+```bash Running the Example
+export LLM_PROFILE_NAME="gpt-5-mini"
+export LLM_MODEL="openhands/gpt-5-mini"
+export LLM_API_KEY="your-api-key"
+# optionally:
+# export LLM_PROFILES_DIR="$PWD/.llm-profiles"
+
+uv run python examples/01_standalone_sdk/35_llm_profiles.py
+```