OpenHands / OpenHands/software-agent-sdk

Allow profile-scoped script commands without a conversation

Open
#5,044 2 comments 0 reactions 1 assignee View on GitHub

@neubig is already working on this.

Since Sep 14, 2026.

enhancement ready-for-dev
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_refs and 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.