Skip to content

feat(ai): parallelize AgentSpec storage writes aligned with Skill - #15165

Merged
KomachiSion merged 1 commit into
alibaba:developfrom
Sunrisea:feat/agentspec-concurrent-save
May 18, 2026
Merged

KomachiSion merged 1 commit into
alibaba:developfrom
Sunrisea:feat/agentspec-concurrent-save

Conversation

@Sunrisea

Copy link
Copy Markdown
Contributor

What is the purpose of the change

When publishing or updating an AgentSpec that contains multiple resource files,
AgentSpecOperationServiceImpl previously serialized all storage writes
(manifest.json + N resources) into a single for loop on the caller thread.
Each write goes through NacosConfigAiResourceStorage and ultimately becomes a
publishConfig round-trip, so end-to-end latency grew linearly with the number
of resources in an AgentSpec.

This PR aligns AgentSpec writes with the existing SkillOperationServiceImpl
implementation by persisting all files concurrently on a dedicated executor,
preserving the original exception semantics.

Brief changelog

  • ai/utils/ExecutorUtils
    • Add AGENTSPEC_STORAGE_IO_EXECUTOR, a fixed-size pool isolated from the
      Skill executor.
    • Add config key nacos.ai.agentspec.storage.io.concurrency
      (default = available processors, min = 1).
    • Rename the previous resolveStorageIoConcurrency to
      resolveSkillStorageIoConcurrency; add the AgentSpec counterpart.
  • ai/service/agentspecs/AgentSpecOperationServiceImpl
    • Extract saveAgentSpecFilesConcurrently(namespaceId, agentSpec, version, uniformId) and replace the serial loop in both
      createDraftWithAgentSpec and writeAgentSpecToStorage.
    • Each save task is submitted via CompletableFuture.runAsync on the
      dedicated executor; tasks wrap the underlying NacosException in a
      CompletionException, which is unwrapped after allOf().join() so the
      outward exception contract is identical to the previous serial code.
    • resolveStorageProvider() is now invoked once per call instead of once
      per file.
  • Tests
    • ai/utils/ExecutorUtilsTest: pin executor isolation, non-null contract,
      and the dedicated com.alibaba.nacos.ai.agentspec.storage-io thread name
      prefix.
    • ai/service/agentspecs/AgentSpecConcurrentSaveTest: pin save count for
      manifest-only and multi-resource cases, distinct StorageKeys, executor
      membership, and NacosException propagation.

Verifying this change

  • mvn -pl ai -am test -Dtest='ExecutorUtilsTest,AgentSpecConcurrentSaveTest' -Dsurefire.failIfNoSpecifiedTests=false → 8/8 pass.
  • mvn -pl ai -am test (full AI module): AgentSpec suites 141/141 pass,
    Skill suites 66/66 pass, SkillAdminControllerTest 24/24 pass — no
    regression on existing tests.
  • mvn -pl ai -am checkstyle:check: pass.
  • Read/delete paths in AgentSpecOperationServiceImpl are intentionally left
    serial (matches Skill behavior).

Follow this checklist to help us incorporate your contribution quickly and easily:

  • Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
  • Format the pull request title like [ISSUE #123] Fix UnknownException when host config not exist. Each commit in the pull request should have a meaningful subject line and body.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in test module.
  • Run mvn -B clean package apache-rat:check spotbugs:check -DskipTests to make sure basic checks pass. Run mvn clean install to make sure unit-test pass. Run mvn clean test-compile failsafe:integration-test to make sure integration-test pass.

- Add dedicated AGENTSPEC_STORAGE_IO_EXECUTOR in ExecutorUtils, isolated
  from the Skill executor and configurable via
  nacos.ai.agentspec.storage.io.concurrency.
- Extract saveAgentSpecFilesConcurrently helper in
  AgentSpecOperationServiceImpl; replace serial for-loop in
  createDraftWithAgentSpec and writeAgentSpecToStorage with one helper
  call. Tasks run on the dedicated executor and unwrap NacosException
  from CompletionException to preserve the previous serial semantics.
- Add ExecutorUtilsTest and AgentSpecConcurrentSaveTest to pin the
  invariants: executor isolation, dedicated thread name, save count for
  manifest-only and multi-resource cases, distinct StorageKeys, and
  NacosException propagation.
@github-actions

Copy link
Copy Markdown

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io


感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式/API/配置参数的变更,如:新增API、新增配置参数、修改默认配置等操作。
如果是,请确保在提交之前,在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档(markdown格式)。

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.00000% with 4 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...vice/agentspecs/AgentSpecOperationServiceImpl.java 92.85% 1 Missing and 1 partial ⚠️
...java/com/alibaba/nacos/ai/utils/ExecutorUtils.java 83.33% 2 Missing ⚠️

📢 Thoughts on this report? Let us know!

@KomachiSion KomachiSion added this to the 3.2.2 milestone May 18, 2026
@KomachiSion KomachiSion added the kind/enhancement Category issues or prs related to enhancement. label May 18, 2026
@KomachiSion
KomachiSion merged commit b6b0fd2 into alibaba:develop May 18, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/Agentspec kind/enhancement Category issues or prs related to enhancement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants