OpenHands / OpenHands/software-agent-sdk
Allow profile-scoped script commands without a conversation
@neubig is already working on this.
Since Sep 14, 2026.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Is there an existing feature request for this?
- I have searched existing issues and feature requests, and this is not a duplicate.
Problem or Use Case
A service may run a deterministic automation script that needs a selected set of saved credentials but does not need an agent or conversation. Today the Agent Server applies an agent profile's secret_refs while launching a conversation. Selecting a profile solely to scope a script command therefore forces callers to create an empty conversation and, with Docker conversation runtimes, an unnecessary runtime.
Automation selectors are a concrete example: a short script scans GitHub, then asks the Automation service to start separate agent conversations for the issues or pull requests it selected. The selector needs its repository-scoped PAT, while only the selected work needs an agent conversation.
Desired Behavior
Allow a caller to execute an Agent Server workspace command with an explicit agent profile ID. The Agent Server resolves only that profile's secret_refs, injects those values into the command environment, and applies the existing Bash output masking. No agent or conversation is created. Omitting the profile preserves current command behavior.
The Python request model is the source of truth and the generated TypeScript client exposes the same optional field. Automation can then treat execution mode and profile selection as independent settings: the profile scopes credentials, while an explicit execution mode determines whether the run is a script or an agent conversation.
Acceptance Criteria
- The typed Bash command request can optionally name an agent profile without accepting raw secret values.
- A profiled command receives saved secrets named by
secret_refsand does not receive unselected saved secrets. - The command's stdout and stderr use the existing secret masking path.
- The command creates no conversation and starts no agent loop.
- Omitting the profile ID preserves existing local and conversation-scoped Bash behavior.
- Unknown profile IDs and unavailable selected secrets fail before the command starts.
- The generated TypeScript client matches the Python request schema, and CI detects drift.
- Focused tests cover selected, excluded, missing, and masked secrets.
Alternatives Considered
Creating an empty conversation provides access to its profile-scoped secret registry, but conflates credential policy with agent lifecycle and wastes a conversation/runtime for deterministic selector code. Passing a PAT directly from host configuration bypasses agent profiles and prevents per-automation least privilege.
Priority / Severity
High - Significant impact on productivity
Estimated Scope
Medium - New feature with moderate complexity
Feature Area
- Agent Server
- Workspace management
- Configuration / Settings
Technical Implementation Ideas (Optional)
Extend the existing ExecuteBashRequest and Bash service rather than defining another execution API. Resolve a per-command SecretRegistry from the profile's secret_refs, then reuse the current environment injection and streaming mask used by conversation-scoped Bash commands.
Additional Context
This is a narrow vertical slice of #4288's runtime-visible credential model and complements #5017. It does not introduce a new secret store, resolver protocol, or conversation type.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.