Multi-Agent Runtime

[arefbehboudi]

This change introduces multi-agent support to JavaClaw and adds an initial agent management experience.

Main changes:

• Added multi-agent runtime support
• Added an Agents page for listing and managing agents
• Each agent now has its own isolated:
  • workspace
  • conversations
  • skills
  • prompt files
• Users can add new agents
• Users can switch the active runtime agent during chat

This lays the foundation for running multiple independent agents in the same app without sharing memory, history, or workspace state.

[martinrevert]

Hi Aref! I bring to your attention info of a special case that could impact in the multi-agent approach. I've integrated OpenRouter as provider, but i didn't sent a PR waiting for your advance on multi-agents and subagents, because that will change for sure the way providers are integrated. As you may know, the thing is there is no oficial Java lib for OpenRouter, you just have to use the same lib and approach as OpenAI, just changing the root URL. Of course to achieve this i had to touch several things on onboarding steps and the provider to keep both options independent even using the same lib. I bring this to your attention because as happens with Ollama, OpenRouter is a nice option to delegate subagents on different models on the same agent/provider and it will be nice to see that also as a multi-subgents option mainly to manage costs but also to have differents concern model (audio, video, image processing, etc), but be aware that to have multi-agent options at same time with OpenAI and OpenRouter will bring this small challenge to reuse the same lib pointing to different URLs. Let me know what you think, i'm interested in your opinion on which could be the best approach on this on the onboarding steps and in the provider integration.

[arefbehboudi]

Hi Aref! I bring to your attention info of a special case that could impact in the multi-agent approach. I've integrated OpenRouter as provider, but i didn't sent a PR waiting for your advance on multi-agents and subagents, because that will change for sure the way providers are integrated. As you may know, the thing is there is no oficial Java lib for OpenRouter, you just have to use the same lib and approach as OpenAI, just changing the root URL. Of course to achieve this i had to touch several things on onboarding steps and the provider to keep both options independent even using the same lib. I bring this to your attention because as happens with Ollama, OpenRouter is a nice option to delegate subagents on different models on the same agent/provider and it will be nice to see that also as a multi-subgents option mainly to manage costs but also to have differents concern model (audio, video, image processing, etc), but be aware that to have multi-agent options at same time with OpenAI and OpenRouter will bring this small challenge to reuse the same lib pointing to different URLs. Let me know what you think, i'm interested in your opinion on which could be the best approach on this on the onboarding steps and in the provider integration.

Hi @martinrevert,
I faced a very similar issue when integrating Grok.

The first problem was the base URL not being configurable, and the second one was the provider selection being tightly coupled to Spring AI auto-configuration. Since Grok doesn’t have an auto-configuration in Spring AI, setting spring.ai.model.chat=grok resulted in failures.

In my MR, I removed the dependency on Spring AI auto-configuration entirely, which solved the issue. Also, providers can now define their own base URL independently.

Based on this, I think we could introduce a custom “OpenAI-compatible” provider abstraction. Since OpenRouter, Grok, and similar providers follow the same API pattern, we can reuse the same implementation and just configure base URL and API key.

[rdehuyss]

I hope to review it tonight 🫣

[rdehuyss]

Ok, so I finally reviewed it! Sorry about the delay... Please also see #53

Some remarks:

• I don't think we're using the Spring Subagents. Was that a deliberate choice? Personally, I'd try to keep as close as possible to their
• Since we can only configure one agent during onboarding, does the default make sense there? Is it not giving too much context to the user too early? Or if we do want it, should we not allow to add multiple agents during onboarding?
• We now have a settings page. Would this mean that all settings would be managed there and we would link to the onboarding again?
• Now seeing the code, I wonder whether it is a good idea that every agent has it's own workspace? I personally sometimes might want one agent to access info from another agent (e.g. if claude code is down, I'd like to switch to another provider). I like the idea of the fallback agent a lot but I think it may fail if it's context lives in a different workspace
• After going through onboarding with only one agent, the chat did not work for me (see screenshot).

Let me know what you think!

[arefbehboudi]

Ok, so I finally reviewed it! Sorry about the delay... Please also see #53

Some remarks:

• I don't think we're using the Spring Subagents. Was that a deliberate choice? Personally, I'd try to keep as close as possible to their
• Since we can only configure one agent during onboarding, does the default make sense there? Is it not giving too much context to the user too early? Or if we do want it, should we not allow to add multiple agents during onboarding?
• We now have a settings page. Would this mean that all settings would be managed there and we would link to the onboarding again?
• Now seeing the code, I wonder whether it is a good idea that every agent has it's own workspace? I personally sometimes might want one agent to access info from another agent (e.g. if claude code is down, I'd like to switch to another provider). I like the idea of the fallback agent a lot but I think it may fail if it's context lives in a different workspace
• After going through onboarding with only one agent, the chat did not work for me (see screenshot).

Let me know what you think!

@rdehuyss Thank you, I really appreciate the time you put into this.

In this phase, I focused on implementing the multi-agent setup, with the intention of addressing sub-agents in the next step. During the implementation, I aimed to stay as close as possible to Spring AI in order to leverage its existing features and abstractions.

Regarding onboarding, showing a default agent may not be the optimal approach, as it can introduce unnecessary context too early. A more suitable approach would be to require only the Agent ID, allowing users to add as many agents as needed. I can update this flow accordingly.

I also introduced a dedicated page for listing agents, where users can view and manage them. Adding a new agent redirects to the same onboarding flow, keeping onboarding as the entry point while management is handled separately.

In terms of architecture, I intentionally designed each agent to have its own workspace. This allows full customization per agent (including prompt, memory, tools, and provider) and enables creating distinctly different agents for different use cases. For scenarios where an agent fails, a fallback agent can be used.

Additionally, I encountered a bug in the dependency
org.springframework.ai:spring-ai-starter-model-openai
which was causing the issue. To resolve this, I replaced it with
org.springframework.ai:spring-ai-starter-model-openai-sdk
and everything is now working as expected.

[rdehuyss]

@auloin - what is your idea here?

[auloin]

Hi @arefbehboudi, thanks for this PR and also the several other you've submitted and merged! I've a few remarks on the bigger picture, plus some immediate issues I've noticed.

Configuration:

• This touches on an earlier remark from @rdehuyss on workspace sharing. At the moment the agents each have a copy of the workspace. It means for each agent I'll need to redo all the onboarding steps, sounds tedious. I think an easy fix would be to pre-fill the agent configuration with the already existing global information (which raises the question of what should happen if the global config is changed...). I don't know if it's possible to share everything though, e.g., conversations format might not be compatible between agents?
• The current implementation makes me think we're aiming for different workspaces, where it makes sense for two workspaces to have independent configurations. This is not a bad thing actually. Then maybe agents should be independent from workspaces? An agent can be configured and linked to different workspaces? Would this work for you as well @rdehuyss?

Code structure:

• Any reasons for having both an agent and agents packages?

Issues:

• I've created another agent via the UI but without completing the entire onboarding... A folder is created for the agent but the new agent is not visible on the UI. Is this expected

[auloin]

Build failed for me with:

> Could not resolve all files for configuration ':providers:openai:compileClasspath'.
   > Could not find org.springframework.ai:spring-ai-starter-model-openai-sdk:.
     Required by:
         project ':providers:openai'

It worked after upgrading the spring-ai-bom to 2.0.0-M4

[auloin]

Should this lead back to the onboarding? I think we might want a proper settings page, separate from the onboarding one. Probably best viewed as a separate task. Should we then disable or remove this link until the work is done?

[auloin]

A click on this link leads to the following:

[auloin]

What do you think of sharing a common layout between this page and the chat page? This way they can share the same header?

[auloin]

If the dashboard is not used in the test, it can also be disabled

Suggested change

	port: 0
	enabled: false

[arefbehboudi]

Hi @arefbehboudi, thanks for this PR and also the several other you've submitted and merged! I've a few remarks on the bigger picture, plus some immediate issues I've noticed.

Configuration:

• This touches on an earlier remark from @rdehuyss on workspace sharing. At the moment the agents each have a copy of the workspace. It means for each agent I'll need to redo all the onboarding steps, sounds tedious. I think an easy fix would be to pre-fill the agent configuration with the already existing global information (which raises the question of what should happen if the global config is changed...). I don't know if it's possible to share everything though, e.g., conversations format might not be compatible between agents?
• The current implementation makes me think we're aiming for different workspaces, where it makes sense for two workspaces to have independent configurations. This is not a bad thing actually. Then maybe agents should be independent from workspaces? An agent can be configured and linked to different workspaces? Would this work for you as well @rdehuyss?

Code structure:

• Any reasons for having both an agent and agents packages?

Issues:

• I've created another agent via the UI but without completing the entire onboarding... A folder is created for the agent but the new agent is not visible on the UI. Is this expected

Hey @auloin, thanks for the feedback!

Configuration / Workspaces

The idea of one workspace per agent comes from OpenClaw.

We can improve this by:

• allowing agents to access other workspaces (with conditions)
• letting new agents reuse existing configs

This would help have different types of agents (coding, marketing, etc.) and even split tasks between them.

Code structure

agent vs agents was a mistake on my side — I will fix it.

Agent not visible in UI

This happens because onboarding was not completed.

Onboarding

I agree — we should have a separate page instead of reusing onboarding.