Skip to content

🙌 OpenHands: AI-Driven Development

settings: add parallel tool calls (tool_concurrency_limit) to Agent Settings (#1312)

Vasco Schiavoc95176f5170f
diff --git a/__tests__/routes/agent-settings.test.tsx b/__tests__/routes/agent-settings.test.tsx
index b80459424f..e5e4048215 100644
--- a/__tests__/routes/agent-settings.test.tsx
+++ b/__tests__/routes/agent-settings.test.tsx
@@ -149,9 +149,44 @@ describe("AgentSettingsScreen", () => {
expect(call.agent_settings_diff).toEqual({
agent_kind: "openhands",
enable_sub_agents: true,
+ tool_concurrency_limit: 1,
});
});
+ it("saves tool_concurrency_limit when changed on the OpenHands path", async () => {
+ const user = userEvent.setup();
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ buildSettings({
+ agent_settings: {
+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+ agent_kind: "openhands",
+ enable_sub_agents: false,
+ tool_concurrency_limit: 1,
+ },
+ }),
+ );
+ const save = vi.spyOn(SettingsService, "saveSettings");
+
+ renderAgentSettingsScreen();
+ await screen.findByTestId("agent-settings-screen");
+
+ const input = screen.getByTestId("sdk-settings-tool_concurrency_limit");
+ await user.clear(input);
+ await user.type(input, "4");
+
+ await user.click(screen.getByTestId("agent-save-button"));
+
+ await waitFor(() => {
+ expect(save).toHaveBeenCalledTimes(1);
+ });
+ const call = save.mock.calls[0]?.[0] as {
+ agent_settings_diff?: Record<string, unknown>;
+ };
+ // Coerced to a number (not the raw input string) via the shared
+ // schema-driven coercion.
+ expect(call.agent_settings_diff?.tool_concurrency_limit).toBe(4);
+ });
+
it("hides sub-agents toggle when ACP is selected", async () => {
const user = userEvent.setup();
vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
@@ -460,6 +495,7 @@ describe("AgentSettingsScreen", () => {
expect(call.agent_settings_diff).toEqual({
agent_kind: "openhands",
enable_sub_agents: false,
+ tool_concurrency_limit: 1,
});
});
diff --git a/src/mocks/settings-handlers.ts b/src/mocks/settings-handlers.ts
index ac73c23749..e1037ffb56 100644
--- a/src/mocks/settings-handlers.ts
+++ b/src/mocks/settings-handlers.ts
@@ -89,6 +89,21 @@ const MOCK_AGENT_SETTINGS_SCHEMA: NonNullable<
secret: false,
required: false,
},
+ {
+ key: "tool_concurrency_limit",
+ label: "Parallel tool calls",
+ description:
+ "Maximum number of tool calls to execute concurrently per agent step. 1 = sequential (default).",
+ section: "general",
+ section_label: "General",
+ value_type: "integer",
+ default: 1,
+ choices: [],
+ depends_on: [],
+ prominence: "major",
+ secret: false,
+ required: false,
+ },
],
},
{
@@ -425,6 +440,7 @@ export const MOCK_DEFAULT_USER_SETTINGS: Settings = {
condenser_max_size: null,
},
enable_sub_agents: false,
+ tool_concurrency_limit: 1,
},
conversation_settings_schema: MOCK_CONVERSATION_SETTINGS_SCHEMA,
conversation_settings: {
diff --git a/src/routes/agent-settings.tsx b/src/routes/agent-settings.tsx
index d5e5771cd2..fa77f2e209 100644
--- a/src/routes/agent-settings.tsx
+++ b/src/routes/agent-settings.tsx
@@ -7,6 +7,7 @@ import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema"
import { SettingsDropdownInput } from "#/components/features/settings/settings-dropdown-input";
import { SettingsInput } from "#/components/features/settings/settings-input";
import { SettingsSwitch } from "#/components/features/settings/settings-switch";
+import { SchemaField } from "#/components/features/settings/sdk-settings/schema-field";
import { AcpCredentialsSection } from "#/components/features/settings/acp-credentials-section";
import { useAcpCredentialForm } from "#/hooks/use-acp-credential-form";
import { BrandButton } from "#/components/features/settings/brand-button";
@@ -14,7 +15,12 @@ import { Typography } from "#/ui/typography";
import { I18nKey } from "#/i18n/declaration";
import { formControlSwitchDescriptionClassName } from "#/utils/form-control-classes";
import { cn } from "#/utils/utils";
-import { SettingsFieldSchema } from "#/types/settings";
+import { SettingsFieldSchema, SettingsValue } from "#/types/settings";
+import {
+ coerceFieldValue,
+ getAgentSettingValue,
+ normalizeFieldValue,
+} from "#/utils/sdk-settings-schema";
import {
displayErrorToast,
displaySuccessToast,
@@ -39,6 +45,7 @@ export const handle = { hideTitle: true };
type AgentType = "openhands" | "acp";
const ENABLE_SUB_AGENTS_FIELD_KEY = "enable_sub_agents";
+const TOOL_CONCURRENCY_FIELD_KEY = "tool_concurrency_limit";
const COMMAND_PLACEHOLDER_FALLBACK = "npx -y <package-name>";
const ACP_CUSTOM_MODEL_KEY = "__custom_model__";
@@ -110,6 +117,23 @@ function AgentSettingsScreen() {
initialSubAgentsEnabled,
);
+ // --- Parallel tool calls (OpenHands path) ---
+ // Surfaced only when the backend schema exposes the field, so older
+ // agent-servers that predate ``tool_concurrency_limit`` hide it cleanly.
+ const toolConcurrencyField = fields?.find(
+ (field) => field.key === TOOL_CONCURRENCY_FIELD_KEY,
+ );
+ const initialToolConcurrency = React.useMemo(() => {
+ if (!toolConcurrencyField) return "";
+ const raw = settings
+ ? getAgentSettingValue(settings, TOOL_CONCURRENCY_FIELD_KEY)
+ : undefined;
+ return normalizeFieldValue(toolConcurrencyField, raw);
+ }, [toolConcurrencyField, settings]);
+ const [toolConcurrency, setToolConcurrency] = useState<string | boolean>(
+ initialToolConcurrency,
+ );
+
// --- ACP path ---
const [agentType, setAgentType] = useState<AgentType>("openhands");
const [commandText, setCommandText] = useState("");
@@ -189,6 +213,11 @@ function AgentSettingsScreen() {
setSubAgentsEnabled(initialSubAgentsEnabled);
}, [initialSubAgentsEnabled]);
+ // Sync the parallel-tool-calls input when settings reload
+ useEffect(() => {
+ setToolConcurrency(initialToolConcurrency);
+ }, [initialToolConcurrency]);
+
if (isLoading) return null;
const isAcp = agentType === "acp";
@@ -210,9 +239,12 @@ function AgentSettingsScreen() {
formatCommand(ACP_PROVIDERS[0]?.default_command ?? []) ||
COMMAND_PLACEHOLDER_FALLBACK;
- // Dirty tracking: for OpenHands path, also check sub-agents toggle
+ // Dirty tracking: for OpenHands path, also check sub-agents toggle and the
+ // parallel-tool-calls input.
const isOpenHandsDirty =
- !isAcp && subAgentsEnabled !== initialSubAgentsEnabled;
+ !isAcp &&
+ (subAgentsEnabled !== initialSubAgentsEnabled ||
+ toolConcurrency !== initialToolConcurrency);
const settingsDirty = isDirty || isOpenHandsDirty;
// The single Save covers both the agent spec and ACP credentials, so it is
// active when either changed, and shows "Saving…" while either is in flight.
@@ -278,13 +310,34 @@ function AgentSettingsScreen() {
},
);
} else {
- // OpenHands path: save agent_kind + sub-agents toggle
+ // OpenHands path: save agent_kind + sub-agents toggle + parallel tool calls
+ const agentSettingsDiff: Record<string, SettingsValue> = {
+ agent_kind: "openhands",
+ enable_sub_agents: subAgentsEnabled,
+ };
+
+ if (toolConcurrencyField) {
+ let coerced: SettingsValue;
+ try {
+ // Reuse the schema-driven coercion + min/max validation rather than
+ // re-implementing it; throws a user-facing message on bad input.
+ coerced = coerceFieldValue(toolConcurrencyField, toolConcurrency);
+ } catch (error) {
+ displayErrorToast(
+ error instanceof Error ? error.message : t(I18nKey.ERROR$GENERIC),
+ );
+ return;
+ }
+ // ``tool_concurrency_limit`` is a non-nullable int (default 1); skip an
+ // empty input rather than sending ``null`` the backend would reject.
+ if (coerced != null) {
+ agentSettingsDiff[TOOL_CONCURRENCY_FIELD_KEY] = coerced;
+ }
+ }
+
saveSettings(
{
- agent_settings_diff: {
- agent_kind: "openhands",
- enable_sub_agents: subAgentsEnabled,
- },
+ agent_settings_diff: agentSettingsDiff,
},
{
onError: (error) => {
@@ -380,6 +433,15 @@ function AgentSettingsScreen() {
</div>
)}
+ {!isAcp && toolConcurrencyField ? (
+ <SchemaField
+ field={toolConcurrencyField}
+ value={toolConcurrency}
+ isDisabled={isSavingAny}
+ onChange={setToolConcurrency}
+ />
+ ) : null}
+
{isAcp && (
<>
<SettingsDropdownInput
diff --git a/src/utils/sdk-settings-field-metadata.ts b/src/utils/sdk-settings-field-metadata.ts
index 66d84e1240..deea62c2e5 100644
--- a/src/utils/sdk-settings-field-metadata.ts
+++ b/src/utils/sdk-settings-field-metadata.ts
@@ -38,6 +38,15 @@ const looksLikeTranslationKey = (value: string | null | undefined) =>
* Labels and descriptions are now handled via convention-based i18n keys.
*/
const FIELD_METADATA: Record<string, SettingsFieldMetadata> = {
+ // Mirrors the SDK's ``tool_concurrency_limit`` constraint (``int`` with
+ // ``ge=1``). Drives both the number input's ``min``/``step`` and
+ // ``coerceFieldValue``'s save-time validation.
+ tool_concurrency_limit: {
+ constraints: {
+ min: 1,
+ step: 1,
+ },
+ },
"llm.top_p": {
constraints: {
min: 0,
diff --git a/src/utils/sdk-settings-schema.ts b/src/utils/sdk-settings-schema.ts
index e2a14505f4..dad46b494a 100644
--- a/src/utils/sdk-settings-schema.ts
+++ b/src/utils/sdk-settings-schema.ts
@@ -336,7 +336,7 @@ function parseBooleanFieldValue(rawValue: string | boolean): boolean | null {
throw new Error(`Expected a boolean value, received: ${rawValue}`);
}
-function coerceFieldValue(
+export function coerceFieldValue(
field: SettingsFieldSchema,
rawValue: string | boolean,
): SettingsValue {