Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: add parallel tool calls (tool_concurrency_limit) to agent settings (#14929)

Vasco Schiavoa251caa86800
diff --git a/frontend/__tests__/routes/agent-settings.test.tsx b/frontend/__tests__/routes/agent-settings.test.tsx
index 3e8e732fcf..63f42e278b 100644
--- a/frontend/__tests__/routes/agent-settings.test.tsx
+++ b/frontend/__tests__/routes/agent-settings.test.tsx
@@ -272,4 +272,64 @@ describe("AgentSettingsScreen β€” minimal generic ACP UX", () => {
"npx -y <package-name>",
);
});
+
+ const openHandsSettingsWithConcurrency = (toolConcurrencyLimit: number) => ({
+ ...MOCK_DEFAULT_USER_SETTINGS,
+ agent_settings: {
+ ...MOCK_DEFAULT_USER_SETTINGS.agent_settings,
+ agent_kind: "openhands",
+ enable_sub_agents: false,
+ tool_concurrency_limit: toolConcurrencyLimit,
+ },
+ });
+
+ it("saves a coerced tool_concurrency_limit on the OpenHands path", async () => {
+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(baseConfig);
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ openHandsSettingsWithConcurrency(1),
+ );
+ const saveSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ renderAgentSettings();
+
+ const input = await screen.findByTestId(
+ "sdk-settings-tool_concurrency_limit",
+ );
+ await userEvent.clear(input);
+ await userEvent.type(input, "4");
+ await userEvent.click(screen.getByTestId("agent-save-button"));
+
+ await waitFor(() => {
+ expect(saveSpy).toHaveBeenCalledTimes(1);
+ });
+ const { agent_settings_diff: diff } = saveSpy.mock.calls[0][0] as {
+ agent_settings_diff: Record<string, unknown>;
+ };
+ // Coerced to a number (not the raw input string) via the shared coercion.
+ expect(diff.tool_concurrency_limit).toBe(4);
+ });
+
+ it("rejects a tool_concurrency_limit above the cap of 10", async () => {
+ vi.spyOn(OptionService, "getConfig").mockResolvedValue(baseConfig);
+ vi.spyOn(SettingsService, "getSettings").mockResolvedValue(
+ openHandsSettingsWithConcurrency(1),
+ );
+ const saveSpy = vi
+ .spyOn(SettingsService, "saveSettings")
+ .mockResolvedValue(true);
+
+ renderAgentSettings();
+
+ const input = await screen.findByTestId(
+ "sdk-settings-tool_concurrency_limit",
+ );
+ await userEvent.clear(input);
+ await userEvent.type(input, "15");
+ await userEvent.click(screen.getByTestId("agent-save-button"));
+
+ // coerceFieldValue throws ("must be at most 10") β†’ error toast, no save.
+ expect(saveSpy).not.toHaveBeenCalled();
+ });
});
diff --git a/frontend/src/mocks/settings-handlers.ts b/frontend/src/mocks/settings-handlers.ts
index 0d4b892e12..20f4601df2 100644
--- a/frontend/src/mocks/settings-handlers.ts
+++ b/frontend/src/mocks/settings-handlers.ts
@@ -101,6 +101,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,
+ },
],
},
{
@@ -379,6 +394,7 @@ export const MOCK_DEFAULT_USER_SETTINGS: Settings = {
model: DEFAULT_MODEL,
},
enable_sub_agents: false,
+ tool_concurrency_limit: 1,
},
conversation_settings_schema: MOCK_CONVERSATION_SETTINGS_SCHEMA,
conversation_settings: {
diff --git a/frontend/src/routes/agent-settings.tsx b/frontend/src/routes/agent-settings.tsx
index 7f8b06a671..59724099be 100644
--- a/frontend/src/routes/agent-settings.tsx
+++ b/frontend/src/routes/agent-settings.tsx
@@ -6,6 +6,7 @@ import { LlmSettingsInputsSkeleton } from "#/components/features/settings/llm-se
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 { useSaveSettings } from "#/hooks/mutation/use-save-settings";
@@ -13,7 +14,7 @@ import { useAgentSettingsSchema } from "#/hooks/query/use-agent-settings-schema"
import { useConfig } from "#/hooks/query/use-config";
import { useSettings } from "#/hooks/query/use-settings";
import { I18nKey } from "#/i18n/declaration";
-import { SettingsFieldSchema } from "#/types/settings";
+import { SettingsFieldSchema, SettingsValue } from "#/types/settings";
import { Typography } from "#/ui/typography";
import {
displayErrorToast,
@@ -25,10 +26,16 @@ import {
resolveSchemaFieldDescription,
resolveSchemaFieldLabel,
} from "#/utils/sdk-settings-field-metadata";
+import {
+ coerceFieldValue,
+ getAgentSettingValue,
+ normalizeFieldValue,
+} from "#/utils/sdk-settings-schema";
import { formatCommand, tokenizeCommand } from "#/utils/shell-tokenize";
import type { ACPProviderConfig } from "#/api/option-service/option.types";
const ENABLE_SUB_AGENTS_FIELD_KEY = "enable_sub_agents";
+const TOOL_CONCURRENCY_FIELD_KEY = "tool_concurrency_limit";
const CUSTOM_PRESET = "custom";
const CUSTOM_MODEL_KEY = "__custom__";
const EMPTY_ACP_PROVIDERS: ACPProviderConfig[] = [];
@@ -110,6 +117,26 @@ export default function AgentSettingsScreen() {
setIsSubAgentsEnabled(initialSubAgentsEnabled);
}, [initialSubAgentsEnabled]);
+ // ── Parallel tool calls (OpenHands mode) ─────────────────────────────────
+ // 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 = useMemo(() => {
+ if (!toolConcurrencyField || !settings) return "";
+ return normalizeFieldValue(
+ toolConcurrencyField,
+ getAgentSettingValue(settings, TOOL_CONCURRENCY_FIELD_KEY),
+ );
+ }, [toolConcurrencyField, settings]);
+ const [toolConcurrency, setToolConcurrency] = useState<string | boolean>(
+ initialToolConcurrency,
+ );
+ useEffect(() => {
+ setToolConcurrency(initialToolConcurrency);
+ }, [initialToolConcurrency]);
+
// ── ACP (ACP mode) ───────────────────────────────────────────────────────
const [agentType, setAgentType] = useState<"openhands" | "acp">("openhands");
const [commandText, setCommandText] = useState("");
@@ -181,7 +208,9 @@ export default function AgentSettingsScreen() {
);
const subAgentsDirty = isSubAgentsEnabled !== initialSubAgentsEnabled;
- const settingsDirty = isDirty || (!isAcp && subAgentsDirty);
+ const toolConcurrencyDirty = toolConcurrency !== initialToolConcurrency;
+ const settingsDirty =
+ isDirty || (!isAcp && (subAgentsDirty || toolConcurrencyDirty));
const credentialsDirty = isAcp && credentialForm.isDirty;
const canSave = settingsDirty || credentialsDirty;
const isSavingAny = isPending || credentialForm.isSaving;
@@ -215,8 +244,27 @@ export default function AgentSettingsScreen() {
// Agent-kind flip: backend resets to defaults, send kind alone.
agentSettingsDiff = { agent_kind: "openhands" };
} else {
- // Sub-agents toggle only.
+ // Sub-agents toggle and/or parallel tool calls.
agentSettingsDiff = { enable_sub_agents: isSubAgentsEnabled };
+
+ if (toolConcurrencyField) {
+ let coerced: SettingsValue;
+ try {
+ // Reuse the schema-driven coercion + min/max (cap-at-10) validation
+ // instead of re-implementing it; throws a user-facing message.
+ coerced = coerceFieldValue(toolConcurrencyField, toolConcurrency);
+ } catch (error) {
+ displayErrorToast(
+ error instanceof Error ? error.message : t(I18nKey.ERROR$GENERIC),
+ );
+ return;
+ }
+ // Non-nullable int (default 1); skip empty input rather than send the
+ // ``null`` the backend would reject.
+ if (coerced != null) {
+ agentSettingsDiff[TOOL_CONCURRENCY_FIELD_KEY] = coerced;
+ }
+ }
}
saveSettings(
@@ -313,6 +361,18 @@ export default function AgentSettingsScreen() {
</section>
)}
+ {/* OpenHands: parallel tool calls β€” only when the schema exposes it */}
+ {!isAcp && toolConcurrencyField ? (
+ <section className="grid gap-4 xl:grid-cols-2">
+ <SchemaField
+ field={toolConcurrencyField}
+ value={toolConcurrency}
+ isDisabled={isSavingAny}
+ onChange={setToolConcurrency}
+ />
+ </section>
+ ) : null}
+
{/* ACP: preset, command, model, credentials */}
{isAcp && (
<>
diff --git a/frontend/src/utils/sdk-settings-field-metadata.ts b/frontend/src/utils/sdk-settings-field-metadata.ts
index 7f62c3ab89..8614bbf7c5 100644
--- a/frontend/src/utils/sdk-settings-field-metadata.ts
+++ b/frontend/src/utils/sdk-settings-field-metadata.ts
@@ -38,6 +38,14 @@ const looksLikeTranslationKey = (value: string | null | undefined) =>
* Labels and descriptions are now handled via convention-based i18n keys.
*/
const FIELD_METADATA: Record<string, SettingsFieldMetadata> = {
+ // SDK constrains this to ge=1; we additionally cap it at 10 in the UI.
+ tool_concurrency_limit: {
+ constraints: {
+ min: 1,
+ max: 10,
+ step: 1,
+ },
+ },
"llm.top_p": {
constraints: {
min: 0,
diff --git a/frontend/src/utils/sdk-settings-schema.ts b/frontend/src/utils/sdk-settings-schema.ts
index 89907584ea..c9994cd35c 100644
--- a/frontend/src/utils/sdk-settings-schema.ts
+++ b/frontend/src/utils/sdk-settings-schema.ts
@@ -106,7 +106,7 @@ function isMinorField(field: SettingsFieldSchema): boolean {
return field.prominence === "minor";
}
-function normalizeFieldValue(
+export function normalizeFieldValue(
field: SettingsFieldSchema,
rawValue: unknown,
): string | boolean {
@@ -311,7 +311,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 {