docs: add get_llm() and get_secrets() to OpenHands Cloud Workspace guide by xingyaoww · Pull Request #401 · OpenHands/docs

xingyaoww · 2026-03-16T21:03:24Z

Summary

Updates the OpenHands Cloud Workspace documentation to cover the new get_llm() and get_secrets() methods for SaaS credential inheritance.

Changes

`sdk/guides/agent-server/cloud-workspace.mdx`

New section: "Inheriting SaaS Credentials" — Documents get_llm() and get_secrets() methods with usage examples and security notes
- get_llm(): Fetches LLM settings from the user's SaaS account and returns a ready-to-use LLM instance
- get_secrets(): Builds LookupSecret references where raw values never transit through the SDK client
New section: "SaaS Credentials Example" — Full expandable example (examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py) showing the simplified flow where only OPENHANDS_CLOUD_API_KEY is needed
Updated page description metadata

Note: A matching branch feat/cloud-workspace-get-llm-secrets has also been pushed to this repo so the SDK CI check (check-examples) can find the docs.

Companion PR

SDK: feat: workspace.get_llm() and get_secrets() for OpenHandsCloudWorkspace credential inheritance software-agent-sdk#2409 (adds the get_llm() and get_secrets() implementation)

- Add 'Inheriting SaaS Credentials' section documenting get_llm() and get_secrets() methods for credential inheritance - Add SaaS Credentials example section with the full expandable example - Update page description to mention SaaS credential inheritance Companion SDK PR: OpenHands/software-agent-sdk#2409 Co-authored-by: openhands <openhands@all-hands.dev>

Matches rename in OpenHands/software-agent-sdk#2409. Co-authored-by: openhands <openhands@all-hands.dev>

sdk/guides/agent-server/cloud-workspace.mdx

Co-authored-by: openhands <openhands@all-hands.dev>

all-hands-bot

🔴 Needs improvement - Documentation claims to be auto-synced but doesn't match the actual SDK example file.

sdk/guides/agent-server/cloud-workspace.mdx

xingyaoww · 2026-03-17T13:41:46Z

@OpenHands please fix all issues #401 (review)

openhands-ai · 2026-03-17T13:42:03Z

I'm on it! xingyaoww can track my progress at all-hands.dev

- Sync get_llm() call to match actual SDK example (simple call, no kwargs) - Sync else branch prompt to match actual SDK example - Clarify dual auth description with specific header names Co-authored-by: openhands <openhands@all-hands.dev>

openhands-ai · 2026-03-17T13:46:17Z

Looking at the work done, all changes have already been committed and pushed to the remote branch in commit c125f0e. Let me summarize:

Summary of Changes

All 3 issues from the PR review (#401 (review)) have been addressed in a single commit (c125f0e), pushed to feat/cloud-workspace-saas-credentials-docs:

Changes made to `sdk/guides/agent-server/cloud-workspace.mdx`:

✅ Code sync fix — get_llm() call (line ~317): Replaced the diverged llm_kwargs pattern with the simple llm = workspace.get_llm() to match the actual SDK example file.
✅ Code sync fix — else branch prompt (line ~357): Replaced the verbose multi-line prompt with the simpler prompt = "Tell me, is there any secret configured for you?" plus a comment, matching the actual SDK example.
✅ Auth description clarification (line 101): Updated the dual authentication description to be more precise — specifying that the Bearer token goes in the Authorization header and the session key (unique per sandbox) in the X-Session-API-Key header.

Checklist:

✅ All 3 unresolved review threads addressed
✅ All 5 review threads on the PR are now resolved
✅ Code block now matches the actual SDK example at examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py from the companion PR
✅ Changes are concise — only the 3 specific issues were touched, no extraneous modifications
✅ Committed and pushed to the PR branch

all-hands-bot

🟢 Good taste — Accurate documentation of an elegant feature that eliminates credential complexity.

malhotra5 · 2026-03-17T14:50:11Z

sdk/guides/agent-server/cloud-workspace.mdx

+You can override any parameter:
+
+```python icon="python"
+llm = workspace.get_llm(model="gpt-4o", temperature=0.5)


Fantastic job on supporting this override

malhotra5

LGTM!

enyst · 2026-03-17T20:23:57Z

sdk/guides/agent-server/cloud-workspace.mdx

+llm = workspace.get_llm(model="gpt-4o", temperature=0.5)
+```
+
+Under the hood, `get_llm()` calls `GET /api/v1/users/me?expose_secrets=true` with dual authentication: the Bearer token (from your Cloud API key) in the `Authorization` header and the session key (unique per sandbox) in the `X-Session-API-Key` header.


I’m really not sure we should let the agent say “dual auth” when one is sent to the client via the other… 😿

enyst · 2026-03-19T19:56:59Z

sdk/guides/agent-server/cloud-workspace.mdx

+
+#### `get_secrets()`
+
+Builds `LookupSecret` references for your SaaS-configured secrets. Raw values **never transit through the SDK client** — they are resolved lazily by the agent-server inside the sandbox:


This is very interesting and cool!

mintlify bot deployed to staging March 16, 2026 21:04 View deployment

openhands-ai bot mentioned this pull request Mar 16, 2026

feat: workspace.get_llm() and get_secrets() for OpenHandsCloudWorkspace credential inheritance OpenHands/software-agent-sdk#2409

Merged

docs: update example filename saas_credentials → share_credentials

bb4ec36

Matches rename in OpenHands/software-agent-sdk#2409. Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 17, 2026 12:19 View deployment

xingyaoww commented Mar 17, 2026

View reviewed changes

sdk/guides/agent-server/cloud-workspace.mdx Outdated Show resolved Hide resolved

xingyaoww commented Mar 17, 2026

View reviewed changes

sdk/guides/agent-server/cloud-workspace.mdx Show resolved Hide resolved

docs: clarify session key is unique per sandbox

30bc164

Co-authored-by: openhands <openhands@all-hands.dev>

mintlify bot deployed to staging March 17, 2026 13:08 View deployment

xingyaoww marked this pull request as ready for review March 17, 2026 13:22

xingyaoww requested a review from enyst as a code owner March 17, 2026 13:22

xingyaoww requested a review from malhotra5 March 17, 2026 13:22

all-hands-bot reviewed Mar 17, 2026

View reviewed changes

sdk/guides/agent-server/cloud-workspace.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-server/cloud-workspace.mdx Outdated Show resolved Hide resolved

sdk/guides/agent-server/cloud-workspace.mdx Outdated Show resolved Hide resolved

mintlify bot deployed to staging March 17, 2026 13:45 View deployment

xingyaoww requested a review from all-hands-bot March 17, 2026 14:29

all-hands-bot approved these changes Mar 17, 2026

View reviewed changes

malhotra5 reviewed Mar 17, 2026

View reviewed changes

malhotra5 approved these changes Mar 17, 2026

View reviewed changes

enyst reviewed Mar 17, 2026

View reviewed changes

enyst mentioned this pull request Mar 19, 2026

docs(sdk): update profile store and cloud workspace example docs #407

Merged

enyst reviewed Mar 19, 2026

View reviewed changes

enyst merged commit 48ac8b0 into main Mar 19, 2026
6 checks passed

enyst deleted the feat/cloud-workspace-saas-credentials-docs branch March 19, 2026 19:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add get_llm() and get_secrets() to OpenHands Cloud Workspace guide#401

docs: add get_llm() and get_secrets() to OpenHands Cloud Workspace guide#401
enyst merged 4 commits intomainfrom
feat/cloud-workspace-saas-credentials-docs

xingyaoww commented Mar 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xingyaoww commented Mar 17, 2026

Uh oh!

openhands-ai bot commented Mar 17, 2026

Uh oh!

openhands-ai bot commented Mar 17, 2026

Uh oh!

all-hands-bot left a comment

Uh oh!

malhotra5 Mar 17, 2026

Uh oh!

malhotra5 left a comment

Uh oh!

enyst Mar 17, 2026

Uh oh!

enyst Mar 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		#### `get_secrets()`

		Builds `LookupSecret` references for your SaaS-configured secrets. Raw values never transit through the SDK client — they are resolved lazily by the agent-server inside the sandbox:

Conversation

xingyaoww commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

sdk/guides/agent-server/cloud-workspace.mdx

Companion PR

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xingyaoww commented Mar 17, 2026

Uh oh!

openhands-ai bot commented Mar 17, 2026

Uh oh!

openhands-ai bot commented Mar 17, 2026

Summary of Changes

Changes made to sdk/guides/agent-server/cloud-workspace.mdx:

Checklist:

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

malhotra5 Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

malhotra5 left a comment

Choose a reason for hiding this comment

Uh oh!

enyst Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

enyst Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

xingyaoww commented Mar 16, 2026 •

edited

Loading

`sdk/guides/agent-server/cloud-workspace.mdx`

Changes made to `sdk/guides/agent-server/cloud-workspace.mdx`: