arXiv CSopen access

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

arXiv:2606.29742v1 [cs.SE] 29 Jun 2026

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition Zishan Su

Junjie Huang

Shiwen Shan

[email protected] The Chinese University of Hong Kong

[email protected] The Chinese University of Hong Kong

[email protected] Sun Yat-sen University

Xingyan Chen

Hui Zeng

Yuxin Su∗

[email protected] Sun Yat-sen University

[email protected] Sun Yat-sen University

[email protected] Sun Yat-sen University

Yanlin Wang

Michael R. Lyu

[email protected] Sun Yat-sen University

[email protected] The Chinese University of Hong Kong

Abstract The adoption of Microservice Architecture (MSA) has revolutionized software engineering by enhancing scalability, agility, and maintainability over traditional monolithic applications. As more developers transition their legacy systems to microservice-based architectures, effective microservice decomposition—partitioning monolithic applications into highly cohesive services—becomes vital. However, this decomposition task presents significant challenges. Manual approaches are time-consuming and labor-intensive. Existing automated methods often fail to capture the necessary semantic insights from complex applications, while naive applications of Large Language Models tend to overlook crucial contextual information and design principles, leading to suboptimal results. To address these challenges, we propose MicroAgent, a ContextAugmented Multi-Agent Framework for Microservice Decomposition. Our framework divides the decomposition process into five distinct subtasks and assigns each to a specialized agent. To enhance the effectiveness of each agent, we provide tailored, multigranularity context that keeps its analysis focused and mitigates information overload. Furthermore, to ensure the decomposition adheres to established design principles, we integrate analytical tools that guide the agents’ decision-making. Experimental evaluations on 10 Java Web applications demonstrate that MicroAgent achieves an average decomposition accuracy of 89.2%, outperforming the state-of-the-art method by 24.6%. We also conduct a case study to highlight the practical benefits of our design.

1

Introduction

Microservice Architecture (MSA) has become a popular paradigm for building complex systems as a composition of small, independent components that communicate with each other through network protocols such as HTTP [33, 53]. Compared to monolithic architectures that are packaged as one complex deployment unit, microservices provide improved scalability, agility, and maintainability [46, 57]. Consequently, many companies, such as Amazon and GitHub [31, 55], has migrated their legacy monolithic applications to microservice-based solutions. ∗ Yuxin Su is the corresponding author of the paper.

The very first task in this migration is microservice decomposition, which partitions the existing monolith into a set of highly cohesive and loosely coupled services [20, 43, 47]. The decomposition results can significantly affect the maintainability, scalability, and performance of the resulting system, since HTTP communication among MSA has a significantly higher overhead compared to local function calls in monolithic applications [46]. Traditionally, this task heavily relies on manual analysis of codebases and business logic [25, 52], making it time-consuming and labor-intensive, especially for large and complex legacy systems with intricate dependencies [46]. To address these challenges, various automatic decomposition methods have been proposed. Existing methods often take a two-step framework for decomposition, which first extracts relevant features from the monolithic application and then applies clustering algorithms to aggregate cohesive functional units for each microservice based on these features [45, 57]. The information is encoded into a graph, where nodes symbolize application elements (e.g, classes, methods), and edges represent certain relationships between them. To enhance subsequent clustering, various methods have been proposed for robust feature extraction, which can be categorized into two types: program analysis-based [24, 30, 32, 38, 45] and semantic analysis-based methods [21, 41, 50, 54]. Program analysis-based methods utilize static or dynamic analysis to extract structural information (e.g. call graph relations, control flow relations) of the monolithic applications to build corresponding graphs. However, static analysis-based methods [30, 45] often struggle to reconstruct comprehensive service invocation relations as critical information, such as routing and dependency, is distributed across configurations beyond static source code. Consequently, they cannot overcome the fragmentation and dynamic nature intrinsic to the original monolith applications. Dynamic analysis-based methods [32, 38], on the other hand, often employ use-case-based analysis with extensive test cases to achieve sufficient code coverage; yet, most real-world monoliths lack such coverage, leading to incomplete dependency extraction and suboptimal decomposition. To complement the sparse information obtained from program analysis, some works [21, 41, 50] attempt to incorporate semantic analysis into graph construction for clustering. These works mostly

Conference’17, July 2017, Washington, DC, USA

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

use off-the-shelf techniques (e.g. Term Frequency, embedding models) to obtain representations for the code elements, which only extract local and shallow semantic features such as class/method names similarity, lacking a global understanding of the in-depth business logic. As a result, existing solutions often fail to achieve accurate and scalable microservice decompositions. The advent of Large Language Models (LLMs) opens up new possibilities for addressing the microservice decomposition task. As LLMs have been trained on large-scale corpus in diverse domains (e.g., code and business), they can leverage the comprehensive pretrained knowledge to understand existing codebases and business logic that the applications imply [29]. However, directly leveraging LLMs to microservice decomposition presents the following challenges: (1) Overlong context length: LLMs can be overwhelmed with the repository-level application codebase, as their performance deteriorates when the number of input tokens increases [35, 36]. This limitation can hinder the complete analysis of the codebase, resulting in fragmented or incoherent microservice boundaries. (2) Lacking context insight: Due to the complex contextual information the applications express, LLMs may struggle to develop a deep-going insight into concrete context, such as class dependencies in complicated applications [59]. This can lead to incorrect decomposition, where interdependent classes are improperly segregated, causing maintenance challenges in the resulting microservices. (3) Oversight on domain knowledge: LLMs can overlook core microservice principles and produce impractical decompositions. For example, they may allocate domain-specific classes into irrelevant services, inducing high coupling; or they may misassign common utilities to a single service, triggering excessive inter-service communication in practical systems. To address these issues, we propose MicroAgent, a ContextAugmented Multi-Agent Framework for Microservice Decomposition. Specifically, we divide the microservice decomposition task into five subtasks, each handled by specific agent(s), including Domain Agent, Clustering Agents, Merging Agent, Common Class Agent, and Review Agent. By breaking down the overall task, each agent can focus on a specific scope of the task, without concentrating on all the repository-level information, thus tackling the first challenge of overlong context. While decomposing the original task into several stages inherently narrows down the context each agent needs to consider, this brings about another problem of what exact context should be exposed to each agent [3, 4]. Hence, we extract and compress the original codebase at varying levels of granularity to generate customized context tailored to each stage in microservice decomposition, covering both application-level and class-level. These contexts are adaptively provided to the agents based on the specific subtask scenario, ensuring each agent has access to the most task-relevant information to delve into. This resolves the second challenge of lacking context insight. To further empower agents with contextual awareness of decomposition tasks and align them with core microservice design principles, we also introduce a suite of specialized tools. This toolkit provides additional decomposition-oriented feedback for agents to assist in their dynamic adjustment, addressing the third challenge of oversight on domain knowledge. We evaluate MicroAgent based on a benchmark of monolithic applications with corresponding microservice versions. Our results

show that MicroAgent achieves a 89.2% accuracy in microservice decomposition on average, which notably surpasses the best baseline – the LLM base model by 24.6%. Particularly, to demonstrate that our framework has incorporated core microservice design principles and can generate practical decomposition results, we measure the effects of common classes identification and assignment, which are often neglected in previous works. In terms of this, MicroAgent showcases a 93.4% F1 score, outperforming the state-of-the-art by 41.1%. To sum up, the main contributions of this work are as follows: • To the best of our knowledge, we propose the first LLM-based agentic framework for microservice decomposition, which decomposes monolithic applications into cohesive microservice partitions, with five agents for tailored subtasks. • We enhance the agents’ contextual understanding through a dual strategy: providing customized, multi-granularity contexts tailored to each subtask, and equipping them with decompositionoriented analytical tools. This approach ensures that agents focus on the most relevant information, leading to practical and accurate microservice partitions. • We evaluate MicroAgent on the benchmark including 10 Java web applications. The results show that MicroAgent achieves an accuracy of 89.2% in microservice decomposition, outperforming the state-of-the-art method by 24.6%. Regarding common class identification and assignment, MicroAgent attains a 93.4% F1 score, improving the best baseline by 41.1%. We also conduct a case study to illustrate how MicroAgent produces practical decomposition.

2 Background and Motivation 2.1 Microservice Decomposition Microservice architecture is a typical software design paradigm where applications are structured as a collection of small, looselycoupled services, each responsible for a distinct aspect of the business logic [33]. In practice, a microservice system typically contains: (i) domain-specific code that implements specific business logic (i.e., an application domain such as ordering, payment, or shipping) and manages domain data; (ii) common code that provides reusable capabilities or shared artifacts (e.g., utility classes, shared interfaces, or data contracts); (iii) API gateways that serve as unified entry points for client requests and handle routing and authentication; (iv) infrastructure components such as databases, message queues, and service registries; and (v) communication mechanisms (e.g., REST, gRPC, or asynchronous messaging) that enable inter-service interaction. To mitigate from a monolithic application and form a microservice system, the first step is to decompose the complex monolith into a set of disentangled microservice candidates [20]. This process is guided by a Domain-Driven Design (DDD) [28] principle, which has been widely adopted in microservice design, such as Microsoft [42]. DDD focuses on aligning software structure with application domains, encouraging developers to encapsulate related business logic and data within clear boundaries. By doing so, DDD helps ensure that each microservice corresponds to a specific business capability and remains cohesive and maintainable. In this work, we follow most previous works and adopt DDD as the primary design principle for microservice decomposition. Specifically, we combine

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

codebase and database analysis with domain-knowledge comprehension to automatically identify and map application domains within the monolithic application, facilitating the transformation into cohesive, domain-aligned microservices.

2.2

Motivating Examples microservice candidate

Catalog Service

correctly partitioned classes Category

incorrectly partitioned classes

Product Item Supplier

create table SUPPLIER (...);

Inventory

create table INVENTORY (...);

BannerData

create table BANNERDATA (...);

……

Monolithic Database Schema Snippet

Part of the Microservice Decomposition Result

(a) Example of LLM hallucination when provided with repository-level context: non-existent classes “Supplier”, “Inventory”, and “BannerData” are assigned to the Catalog Service partition. Monolithic Code Snippet OrderServiceImpl.java:

Monolithic Code Snippet OrderItemVo.java: ... public class OrderItemVo { private Long skuId; private BigDecimal price; private Integer count; ... }

Cart Service CartService CartServiceImpl CartItemVo OrderItemVo ……

Part of the Microservice Decomposition Result

public SubmitOrderResponseVo submitOrder(OrderSubmitVo submitVo) { ... List<OrderItemVo> orderItemVos = order.getOrderItems().stream().map((item) -> { OrderItemVo orderItemVo = new OrderItemVo(); orderItemVo.setSkuId(item.getSkuId()); orderItemVo.setCount(item.getSkuQuantity()); return orderItemVo; }).collect(Collectors.toList()); WareSkuLockVo lockVo = new WareSkuLockVo(); lockVo.setOrderSn(order.getOrder().getOrderSn()); lockVo.setLocks(orderItemVos); try { wareSkuService.orderLockStock(lockVo); log.info("Stock locked successfully!"); } ... return responseVo;

WareSkuServiceImpl.java: public Boolean orderLockStock(WareSkuLockVo wareSkuLockVo) { ... List<OrderItemVo> itemVos = wareSkuLockVo.getLocks(); log.info("Start to lock the stock, Order No. = {}, Items = {}", wareSkuLockVo.getOrderSn(), itemVos.size()); List<SkuLockVo> lockVos = itemVos.stream().map(...).collect(Collectors.toList()); for (SkuLockVo lockVo : lockVos) { ... } log.info("Stock locked successfully, Order No. = {}", wareSkuLockVo.getOrderSn()); return true; }

(b) Example of LLM’s insufficient use of concrete code context: “OrderItemVo” is assigned to Cart Service, while the code snippet shows it is used in order submission and stock-locking logic.

Figure 1: Motivating examples demonstrating the challenges of directly utilizing LLMs for microservice decomposition. In this section, we use two illustrative real-world examples to demonstrate the challenges of directly applying LLMs to decompose the monolithic version of JPetstore [10] and gulimall [11]. JPetstore [10] is a pet-store web application, and gulimall [11] is an online shopping mall application. We provide Deepseek-V3.2 [37] and GPT5.2 [17] with the monolith’s raw source code and the database file, and require LLMs to output the class-level microservice decomposition result. Figure 1a shows the LLM-generated decomposition for Catalog Service in JPetstore application, in which classes named “Supplier”, “Inventory” and “BannerData” are assigned to this service partition. However, these three terms only appear as tables in the database schema and do not correspond to any classes in the source code, suggesting that LLM may mistakenly interpret database entities

Conference’17, July 2017, Washington, DC, USA

as class names. This indicates that when overly long, repositorylevel information is provided as context, LLMs may hallucinate and undermine the accuracy of microservice decomposition. For gulimall application, the decomposition result contains three partitions reflecting different application domains: Cart Service, Order Service, and Ware Service. In Figure 1b, LLM assigns the class “OrderItemVo” as a common class shared between both Cart Service and Order Service. However, a closer inspection of the code reveals that “OrderItemVo” models items within a customer order and is used in order submission and stock-locking workflows. Accordingly, it should be placed in Order Service and Ware Service, rather than in Cart Service. This error suggests that the LLM may rely heavily on surface cues (e.g., similarity between “OrderItemVo” and “CartItemVo”) while failing to fully incorporate usage context and call relationships. Consequently, LLM fails to adhere to microservice design principles, which leads to unnecessarily high coupling among different services. Our Insights. From these observations, we derive three key insights: #1 Utilization of a multi-agent framework to divide complex tasks. We break down the intricate task of microservice decomposition into multiple subtasks, creating a workflow that is collaboratively executed by multiple agents. This approach narrows the focus for each agent, allowing them to concentrate solely on their designated subtask and avoiding the burden of managing excessive context from a large, comprehensive task. #2 Customizing hierarchical context for better utilization of context window. Since directly providing raw application code and database information to agents is impractical, we preprocess and compress the original context before it is used by LLMs in their decomposition subtasks. Through extraction, summarization, and relationship analysis, we construct context at varying granularities, both at the application level and class level, and carefully select the scope of context to expose to each agent. #3 Specialized tools designed to assist further analysis. To aid with agents’ understanding of the code, we design analytical tools that enable them to explore underlying context among classes and align with core microservice design principles.

3

Methodology

Figure 2 illustrates the framework of MicroAgent for microservice decomposition. To address the problems of overlong context length and limited context insights, we split the complex decomposition task into five subtasks, and assign specialized agent(s) to each subtask. These agents collaborate to achieve the shared goal of effective microservice decomposition. Our design of these five subtasks adheres to the principles of domain-driven design (DDD), which consists of two phases [56]: (1) strategic phase that identifies business domains and establishes application domain boundaries; (2) tactical phase that further refines the structure and responsibilities within each bounded context. In microservice architecture, each bounded context serves as a microservice candidate. Accordingly, our first three agents implement the strategic phase (discovering and shaping bounded contexts), while the last two agents complete the tactical phase (refining the contents of each context).

Conference’17, July 2017, Washington, DC, USA

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

Input from context (retrieved by tools)

Clustering Agents

Output from successor task / Input for predecessor task

Domain D

Domain C

Merging Agent

Classes in the monolithic application Domain A: This domain is responsible for …

Domain Agent

Domain B: This domain handles …

Identify core business domains

Domain C: This domain mainly covers …

Generate detailed descriptions for each domain

Domain D: This domain provides …

1. Domain Identification

Domain D

Domain C

Domain A

Domain B Domain B

Merge closely-related domains to satisfy expected number

Collection of Domain-Specific Classes in Each Domain

3. Domain Merging

Search for semantically related classes

Identified Domains with Descriptions

Search for dependency related classes

Domain A

2. Domain Clustering Domain CD

Monolith Hierarchy Database Summary Application-Level Context

Application Source Code Application Database Script

v

Context Compression Class-Level Context

Class Summaries

Class Basic Information

Class Source Code

Class Dependency Graph

Domain A

Domain B

Updated Domains after Merging

Common Class Agent

Review Agent Domain CD

Partition CD Observed Class 2 Unassigned

ss 1 on Cla Comm

Observed Class 3

Partition A

Partition B

Decomposition Result

Domain A

Domain B

Observed Class 1

Search for dependency related classes to make adjustment

Updated Domains with Common Classes

Common Class 2

Rank dependency entropy and ratio to get potential common classes Derive related classes from dependency Check and propagate original assignment

5. Decomposition Refinement

4. Common Class Assignment

Figure 2: Overview of the multi-agent workflow of MicroAgent. Specifically, in the first subtask Domain Identification, the Domain Agent is responsible for analyzing business logic and identifying candidate domains. Then, in Domain Clustering, the Clustering Agents are dynamically instantiated for each domain, where each agent collects and clusters domain-specific classes associated with its respective domain. To avoid overly fragmented contexts and to meet the desired number of microservices, in Domain Merging, the Merging Agent evaluates the identified domains and merges closely related ones into more cohesive bounded contexts, completing the strategic phase of DDD. The remaining subtasks correspond to the tactical phase of DDD. In Common Class Assignment, the Common Class Agent identifies classes shared across domains and assigns them to the appropriate ones. Finally, the process concludes with Decomposition Refinement. The Review Agent examines remaining unassigned classes and decides whether to incorporate them into existing domains or leave them unassigned based on relevance and cohesion. The resulting partitions of this subtask constitute the final microservice candidates. Throughout this process, agents enhance their contextual understanding through tool invocation. As illustrated in Table 1, each agent has access to a distinct set of tools. There are two types of agent tools: the retrieval tools and the specialized tools. The retrieval tools provide raw contextual information directly, while the specialized tools perform in-depth analysis, integrating microservice design principles. The context available to agents is organized into two levels of granularity, including the application-level context and the class-level context. In the rest of this section, we will introduce the design of context management and multi-agent workflow in detail.

3.1

Context Compression

As discussed in Section 1 and Section 2, directly providing repositorylevel code to the agents would be excessively verbose and could be a burden to their memory. To ensure the agents receive context at an appropriate level of granularity, we compress the context in advance from two perspectives: application-level and class-level. 3.1.1 Application-Level Context. We extract application-level context and provide it to all agents, offering a global and preliminary view of the code and database structure. It includes: (1) Monolith Hierarchy: We extract the package and class lists directly from the source code and organize them in a hierarchical format. This hierarchical structure offers a concise, top-level overview that helps agents infer potential functionalities based on package divisions. (2) Database Summary: Database definitions in monolithic applications can vary from SQL schema to non-SQL document. Therefore, we preprocess the database files by requiring an LLM to provide metadata summaries based on the database file to provide a unified and more LLM-friendly [44] structure. 3.1.2 Class-level Context. While application-level context offers a global perspective for agents, class-level context is essential for accessing detailed information within individual classes or across multiple classes. Class-level context is further categorized into two components: class-level sketch, which includes class summaries and basic information, and class-level details, which encompass the class dependency graph and source code. The Domain Agent is provided with a brief class-level sketch to understand the functionalities of the entire monolithic application and to identify all business

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

Conference’17, July 2017, Washington, DC, USA

Table 1: Tool type, descriptions and agents accessible Tool Type

Retrieval Tools

Specialized Tools

Tool

Tool Descriptions

Agents

get_class_hierarchy get_database_summary

Get monolith hierarchy. Get database summary for the application.

All Agents

get_all_class_summaries get_class_summary get_class_basic_info

Get summaries for all classes. Get summary for single class input. Get basic information for input class.

Domain Agent

get_class_relation_and_code search_file

Get relationship and source code for input class. Search for a term in a file and return matching lines.

All Except Domain Agent

codebase_semantic_search

Search for class summaries that are semantically related to a natural language query.

Clustering Agents

get_related_class_list

For a list of classes, find all classes they depend on and all classes that depend on them, and return the unique union.

Clustering Agents, Review Agent

rank_dependency_entropy_and_ratio get_more_potential_common_classes

Calculates both incoming and outgoing dependency entropy and ratio for all classes. Takes a list of potential common classes and returns all their dependents and dependencies that could be additional potential common classes. Takes a dict of common classes with their domain assignments and relationship types, and return a propagated assignment.

Common Class Agent

assign_common_class_list

domains. For the subsequent four agents, detailed class-level information is made available to support precise decomposition. Below, we introduce the contents of each component in detail. (1) Class Summaries: We utilize an LLM to generate a compact and informative summary for each class. These summaries include: (a) the main purpose of the class, (b) its key methods and the functionalities of the methods, and (c) any additional significant information identified by the LLM. This distills the source code of each class while maintaining its expressiveness. (2) Class Basic Information: We sketch the class by extracting key elements of each class and wrapping them in a JSON format. The key elements include the class name, fields, method signatures, annotations, and dependencies. This context delivers a clear abstract of each class, enabling agents to understand its core attributes efficiently. (3) Class Dependency Graph: We track syntactic and semantic relations among code elements by applying class dependency analysis. For syntactic analysis, we utilize JavaParser [18], a lightweight static analysis tool, to generate an Abstract Syntax Tree (AST). For semantic derivation, we employ Class Hierarchy Analysis (CHA) [26]. This information is also serialized into JSON format.

3.2

Multi-Agent Workflow

In this subsection, we present an overview of each subtask within the multi-agent workflow. For each stage, we begin by outlining the role and objectives of the corresponding agent. Next, we delve into the specific context required for the task and detail the design of the associated toolkit. 3.2.1 Domain Identification. At this stage, the goal for Domain Agent is to develop a comprehensive understanding of the entire monolithic application and identify core application domains. Given the desired number of target microservices 𝑛, the agent identifies a set of at least 𝑛 domains and generates a detailed description for each domain. Context Analysis. This stage involves conducting a high-level overview of the monolithic application without delving into the implementation details. Therefore, we provide the agent with class summaries and basic class information, rather than details related to source code or class dependencies. Toolkit Design. To gather application-level information, we introduce the get_all_class_summaries tool, which allows the agent to obtain an outline of the entire application. Given that applications

typically consist of numerous classes, we additionally provide classlevel tools that allow the agent to selectively access information about individual classes. These include the get_class_summary and get_class_basic_info tools. 3.2.2 Domain Clustering and Domain Merging. The objective of these two subtasks is to derive a qualified set of domains with the classified domain-specific classes. The agents cluster domainspecific classes for the domains identified in the preceding subtask and merge closely related domains when necessary. During the domain clustering stage, the identified domains and their corresponding descriptions obtained from the first subtask serve as inputs for dynamically instantiated Clustering Agents. Each domain is assigned to a dedicated Clustering Agent, ensuring that the number of agents corresponds to the number of domains identified. The task description for each agent is also dynamically generated, incorporating the specific domain’s objectives along with descriptions of all other domains, as illustrated in Figure 2. This enables each agent to be aware of domain boundaries and can accurately cluster classes within its assigned domain. The output of each agent is a list of classes associated with its respective domain, and the clustering results across all domains are concatenated for use in subsequent subtasks. The domain merging subtask is optional and is invoked if the number of identified domains exceeds the desired number of microservices. In such cases, the Merging Agent is employed. This agent is provided with the class collections from all domains and is tasked with merging certain domains to achieve the target number of microservices while preserving domain coherence. Context Analysis. For both subtasks, agents are supposed to determine the specific functionalities and interactions of classes, necessitating a more fine-grained context regarding the source code and class dependencies. For the Clustering Agent, however, the challenge lies in narrowing the scope of analysis to a relevant subset of classes for a particular domain. We therefore design specialized tools to assist this agent. Toolkit Design. To facilitate access to code details and class dependencies, we provide two retrieval tools: get_class_relation_and_code and search_file. These tools are utilized by both the Clustering Agents and the Merging Agent. As discussed earlier, narrowing the scope of domain clustering is critical for effective microservice decomposition. To achieve this, we design specialized tools tailored for the Clustering Agent. Drawing inspiration from the cohesion characteristics of microservices [33, 53], we leverage both semantic

Conference’17, July 2017, Washington, DC, USA

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

search and dependency analysis to refine the scope of clustering. The following tools support this process: (i) codebase_semantic_search: Motivated by RAG technique [34], this tool employs a pre-trained sentence transformer [19] to generate embeddings for each class based on its summary. The Clustering Agent can input a natural language query (e.g. domain description) into the tool, and this tool calculates the semantic similarity between the query and the class summaruy of each class. The top-K most semantically similar class summaries are returned as the result. This enables the agent to identify candidate classes that are semantically aligned with the target domain, providing an initial focus for further analysis. (ii) get_related_class_list: While the codebase_semantic_search tool identifies classes based on semantic similarity, this tool provides a complementary perspective by focusing on class dependencies. With a list of class nodes as inputs, this tool extracts all the reachable class nodes that have a direct dependency/dependent relationship with any node in this list. By integrating dependency analysis with semantic similarity, this tool enhances the agent’s ability to understand the structural and functional relationships within the codebase, thereby improving the precision of domain clustering. 3.2.3 Common Class Assignment. In this subtask, the target for Common Class Agent is to identify common classes and assign them to the corresponding domains. Common classes refer to classes that need to be allocated into multiple microservice candidates. Unlike domain classes that implement domain-specific business logic rules, common classes provide cross-domain support or cross-cutting capabilities. Motivated by the previous research [57], we distinguish two types of common classes based on the direction of cross-domain dependencies: (1) Multi-domain depended-on common classes: classes that are depended on by multiple domains. Typical examples include reusable utilities (e.g., utility/helper classes) and shared data contracts (e.g., DTO/VO/TO models). (2) Multi-domain dependent common classes: classes that depend on multiple domains. These classes typically serve as coordinators or mediators across domains, such as facades or orchestration components. The agent first identifies these two types of common classes, then detects the domains that depend on or are dependent on by each common class, and finally assigns the class to the corresponding domains based on these dependency relations. Context Analysis. At this stage, understanding the context of source code and class dependencies is crucial for the Common Class Agent to determine whether a class should be shared across multiple domains. Given the large number of classes in monolithic applications, locating potential common classes with minimal oversight is challenging. Therefore, specialized tools are necessary for in-depth analysis of class relationships. Toolkit Design. To enable the agent’s exploration of class details, we provide retrieval tools like get_class_relation_and_code and search_file. To further assist the agent in identifying the potential common classes accurately, we also design three specialized tools: (i) rank_dependency_entropy_and_ratio: To facilitate the discovery of the two types of common classes mentioned above, with the inspiration from the metrics measuring purity in microservices[32, 57], we propose to use Dependency Entropy, utilizing Shannon entropy[51] to measure the “domain purity" of classes. Based on

the two dependency directions, Dependency Entropy contains incoming and outgoing dependency entropy. An intuition is that classes that are commonly used by multiple domains, such as utility classes, should have high incoming dependency entropy, indicating low domain purity. And for the common classes that depend on multiple domains, like coordinator classes, should have high outgoing dependency entropy. Hence, we utilize Dependency Entropy to measure how diverse a class’s dependencies are distributed across different business domains. We compute this metric separately for incoming and outgoing dependencies. For the incoming dependency entropy 𝐻𝑖𝑛 (𝐶) of a class 𝐶, the tool first collects the set of business domains D = {𝐷 1, 𝐷 2, . . . , 𝐷𝑘 }, where each domain 𝐷𝑛 is included if it contains at least one class that depends on 𝐶. In the dependency graph, this means there exists at least one edge from a class in 𝐷𝑛 to 𝐶. Thus, 𝑘 denotes the number of distinct domains that have incoming dependencies to 𝐶. The incoming dependency Í entropy is defined as: 𝐻𝑖𝑛 (𝐶) = − 𝑘𝑖=1 𝑃 (𝐷𝑖 ) log2 (𝑃 (𝐷𝑖 )), where Number of classes from domain 𝐷𝑖 that 𝐶 depends on 𝑃 (𝐷𝑖 ) = . The tool ranks Total number of classes that depends on C all the classes and returns the classes with the top-K highest entropy. Also, it attaches the calculation result of the incoming dependency 𝑖𝑛 (𝐶 ) ratio and outgoing dependency ratio, e.g., 𝑅𝑎𝑡𝑖𝑜𝑖𝑛 (𝐶) = 𝑁𝑁𝑜𝑢𝑡 (𝐶 ) , providing additional context by giving the fraction of incoming and outgoing dependencies. These ratios indicate the dominant dependency direction (incoming vs. outgoing), which helps characterize common classes when bidirectional dependencies exist. This metric helps the agent filter out domain-specific classes that interact with multiple domains, which are not the common classes we aim to identify. Under the microservice principle of high cohesion, such classes are expected to exhibit high domain purity, meaning that most of their dependencies stay within a single domain rather than being spread across domains. As a result, their dependency distribution is concentrated, and their dependency entropy remains low. (ii) get_more_potential_common_classes: While the previous tool identifies some potential common classes, this tool explores further by retrieving lists of related classes with direct edges in the dependency graph, promoting the discovery of additional candidates. (iii) assign_common_class_list: With the assistance of tools (i)(ii), the agent can discover adequate common classes candidates. By leveraging the retrieval tools to look into the code details and dependencies, it can make an initial decision on the common class assignment. However, the complexity of the assignment grows when there are multiple common classes with both incoming and outgoing dependency relationships. The complexity makes it difficult for the agent to give a complete and accurate assignment directly. For example, if class 𝐴, 𝐵, 𝐶 are common classes identified by the agent, with dependency 𝐴 → 𝐵 → 𝐶, if class 𝐴 is assigned to a partition, then class 𝐵, 𝐶 should also be assigned since 𝐴 depends on them. This propagation of assignment is non-trivial and can be easily neglected by agents. In order to fully integrate dependency analysis with the code understanding ability of LLM, and to derive a more reliable assignment result, we propose a propagation algorithm to validate and update the current assignment. Take incoming dependency as an example. As shown in Algorithm 1, the tool begins by constructing

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

Conference’17, July 2017, Washington, DC, USA

Table 2: Breakdown of our benchmark applications. Algorithm 1: Common Class Propagation Algorithm Procedure AssignCommonClass(original_assignment) incoming_graph ← Build graph where edge "A ← B" means "B depends on A" 3 incoming_sorted ← TopologicalSort(incoming_graph)

1 2

4 5 6 7

8

for common_class ∈ incoming_sorted do 𝑑𝑒𝑝𝑒𝑛𝑑𝑒𝑛𝑡𝑠 ← Get dependents of common_class from 𝑖𝑛𝑐𝑜𝑚𝑖𝑛𝑔_𝑔𝑟𝑎𝑝ℎ for 𝑑𝑒𝑝𝑒𝑛𝑑𝑒𝑛𝑡 ∈ 𝑑𝑒𝑝𝑒𝑛𝑑𝑒𝑛𝑡𝑠 do Propagate the domain assignment of dependents to the original assignment of common_class; return updated_assignments

an incoming dependency graph for the input common classes (Line 2). Next, it performs a topological sort on this graph to establish the order of dependencies (Line 3). Following the sorting, the tool iterates through each class in the topological order, retrieves its dependents and their assigned domains (Line 4-5), and propagates the domains accordingly (Line 6-7). This propagation algorithm ensures that the current assignment is updated systematically based on the dependency structure. 3.2.4 Decomposition Refinement. This is the final stage of the workflow. The Review Agent is primarily tasked with making necessary adjustments to improve the overall quality of the decomposition, including (i) inspecting classes that remain unassigned and deciding whether (and where) they should be incorporated into any partition; (ii) revisiting previously assigned classes to resolve inconsistencies. The output of this subtask is the final set of partitions (i.e., microservice candidates) for the entire decomposition task. As the last step, it serves as a global check that consolidates earlier decisions and corrects residual issues before producing the final decomposition. Context Analysis. In this subtask, the agent focuses on context related to source code and class dependencies, as it explores the details of each unassigned class or any class requiring adjustment. Toolkit Design. Here we reuse the practical tools search_file, get_class_relation_and_code, and get_related_class_list to enable the agent to acquire detailed information about the classes. These tools are introduced in section 3.2.2. The complete prompt templates, including system prompts and task-specific user prompts, are provided in our artifacts.

4

Evaluation

We evaluate MicroAgent by answering the following research questions (RQs): • RQ1: How effective is MicroAgent in microservice decomposition? • RQ2: How effective is MicroAgent in assigning common classes to their microservice partitions? • RQ3: How does each component contribute to MicroAgent? • RQ4: How does MicroAgent perform with different LLMs?

4.1

Experimental Setup

4.1.1 Benchmark Applications. Our benchmark consists of 10 Java applications, covering 49 services in total. This benchmark relates to various business topics, and meanwhile includes the most common Java web frameworks [23]. Among these ten applications, five are commonly used in previous works [32, 45, 57]: SpringPetclinic [13], PartsUnlimitedMRP [8], 7ep-demo [5], JPetStore [10], and AcmeAir [6]. The microservice versions for these monolithic

Repository JPetstore Spring-Petclinic PartsUnlimitedMRP 7ep-demo Acme Air youlai-mall PassJava microservices-platform goodsKill gulimall

# of Classes

LOC

# of Microservices

24 23 53 47 32 352 73 103 143 379

1,409 752 4,407 2,326 2,048 14,127 10,086 12,166 7,856 20,714

3 4 5 4 4 6 6 5 5 8

applications can be publicly accessed [1, 9, 12, 57]. Apart from these five applications, we additionally select five larger microservice repositories [7, 11, 14–16], which satisfy the criteria: (1) the number of classes is more than 50; (2) stars on GitHub are more than 2k; (3) the line of code is larger than 5k; (4) the number of microservices is no less than 5. For these five applications with only microservice versions publicly available, we construct the corresponding monoliths with the assistance of LLM tools. Each monolith is first validated to pass compilation, functional tests and E2E tests. Then these monoliths were independently reviewed by three authors to ensure no business logic is lost and no microservice-specific artifacts remain. Table 2 shows the details of our selected benchmark applications, including number of classes for decomposition, LOC (Line of Code), and number of microservice partitions. 4.1.2 Baselines. Our baselines include Mono2Micro [32], CARGO [45], MonoEmbed [49], MOSAIC [30] and an LLM baseline. Among these, CARGO and MOSAIC are method-level decomposition tools, and the rest are all class-level decomposition tools. For the LLM baseline, we provide the original application code, database scripts, and the target number of microservices as input, and prompt the model in a zero-shot setting to generate decomposition results, thereby avoiding bias from few-shot examples [58]. 4.1.3 Models. We select three widely used LLM models: DeepseekV3.2 [37], GPT-5.2 [17], and Claude Sonnet 4.5 [2] to conduct our experiment, due to their accessibility and stability. For all models, we set the temperature to 0 to get a more deterministic result. 4.1.4 Metrics. We use architectural metrics and similarity metrics to evaluate the overall decomposition results. Besides, we also verify the effects of correctly assigning common classes to further demonstrate the practicability of our decomposition results. Architectural Metrics. We adopt three widely used metrics from prior work to measure how well the decomposition follows microservice design principles: (1) Code Modularity (CMod) [57] measures the cohesion and coupling of the decomposition on the static call graph. For each partition, it is computed as the ratio of intra-partition edge weights to the sum of intra-partition and inter-partition edge weights. We calculate the modularity for each partition separately and compute the mean across all partitions. Higher values indicate better modularity. (2) Cyclic (In-)Dependence (CiD) [57] evaluates the proportion of partition pairs that are free from cyclic call dependencies. Higher values indicate fewer undesirable cyclic dependencies. (3) Business Context Purity (BCP) [32, 45, 57] measures how concentrated the business use cases are within each partition using entropy. Higher values indicate that each partition better aligns with the Single Responsibility Principle [40].

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

Similarity Metrics. As revealed by the recent study [57], although architectural metrics have been widely utilized for evaluation in previous works, they can only offer a partial and theoretical view of the decomposition quality, since high architectural metrics can also lead to low quality or impractical decomposition results. Therefore, to evaluate how accurate and practical our decomposition results are, we compare them with the ground truth decomposition results (i.e., the corresponding microservice versions). Weighted Similarity (WS): This metric measures the accuracy of a produced decomposition 𝑃 compared with the reference 𝑅, refining the calculation in [57] to compute in both directions. For each partition 𝑝𝑖 in 𝑃, we find the most overlapping partition 𝑟 𝑗 in |𝑝 ∩𝑟 |

𝑖 𝑗 𝑅 and calculate 𝑆𝑖𝑚(𝑝𝑖 , 𝑟 𝑗 ) = max( |𝑝 . The directional weighted 𝑖 |,|𝑟 𝑗 | ) Í similarity is WS𝑃→𝑅 = 𝑖 𝑆𝑖𝑚(𝑝𝑖 , 𝑟 𝑗 ) × 𝑤 𝑗 , where 𝑤 𝑗 is the proportion of |𝑟 𝑗 | relative to the sum of all matched partition sizes. WS𝑅→𝑃 is computed analogously. The overall weighted similarity is the harmonic mean of both directions. A higher value indicates higher similarity to the ground truth. To ensure classes that are not considered in the reference decomposition do not influence the results, we exclude those uncounted classes (usually w.r.t. underlying infrastructure) in the produced decomposition before calculation. Cluster-to-cluster Coverage (𝑐2𝑐𝑐𝑣𝑔 ) [39, 57]: This metric represents to what extent a produced decomposition overlaps with the ground truth. It measures the proportion of partitions whose best match exceeds a similarity threshold percentage 𝑡ℎ𝑐𝑣𝑔 . Following the same bidirectional scheme as weighted similarity, we define | {𝑝 :𝑆𝑖𝑚 (𝑝𝑖 ,𝑟 𝑗 ) ≥𝑡ℎ𝑐𝑣𝑔 } | c2c (𝑃→𝑅) = 𝑖 , compute c2c (𝑅→𝑃 ) analogously, |𝑃 | and take the harmonic mean. We report results at 50% (some overlap), 75% (moderate overlap), and 90% (high overlap). For example, with 𝑡ℎ𝑐𝑣𝑔 = 90%, a higher value of c2c𝑐𝑣𝑔 indicates that there are more partitions in 𝑃 that are at least 90% similar to the reference decomposition 𝑅. Common Class Assignment Metrics. To further demonstrate how well MicroAgent generates practical decomposition results, we evaluate the effects of common classes identification and assignment from the service level. For each service 𝑠 and common class 𝑐, the reference allocation is defined as: 𝑠 should contain 𝑐 if 𝑠 includes any class that depends on 𝑐. We compare this reference allocation against the actual decomposition result to compute True Positives (TP, correctly allocated), False Positives (FP, redundantly allocated), and False Negatives (FN, missing allocations). Then we calculate the Precision, Recall, and F1 based on these. Higher precision indicates fewer unnecessarily allocated common classes, while higher recall indicates that the decomposition misses fewer common classes that services depend on.

4.2

RQ1: Effectiveness of MicroAgent in Microservice Decomposition

We evaluate the performance of our framework against the baselines with both architectural metrics and similarity metrics to answer RQ1. The results are displayed in Table 3 and Figure 3. Both MicroAgent and the base LLM model use Deepseek-V3.2 as backbone. Among the approaches, four of six tools can produce results for all ten benchmark applications. CARGO [45] can only obtain results for three applications, and MOSAIC [30] fails to decompose two

applications. These limitations may stem from restricted framework compatibility, or from certain applications falling outside the tools’ underlying assumptions. In terms of Architectural Metrics, MicroAgent achieves the highest scores in CMod, showing an 11.9% improvement compared with the best baseline MOSAIC. For cyclic dependency, MicroAgent attains the highest percentage of 98.6%, which is close to 100%, indicating that our decomposition results are largely free of cyclic dependence. For cyclic dependency, MicroAgent gains a lower score in BCP compared with MOSAIC. By inspecting case studies, this is likely because MicroAgent considers common classes shared across partitions, which reduces business context purity. For Similarity Metrics, MicroAgent exhibits significant improvement in the weighted similarity (i.e., accuracy) when compared with the ground truth decomposition. It achieves an 89.2% accuracy on average across the benchmark applications, which outperforms the best baseline, LLM base model, by 24.6%. Figure 3 further demonstrates that MicroAgent consistently surpasses other baseline methods across all the benchmark applications. For the similarity coverage, our approach improves by 17.7%, 36.9%, and 409.6% regarding the metrics of 𝑐2𝑐𝑐𝑣𝑔 when the threshold is 50%, 75%, and 90%, respectively. Table 3: Results of architectural metrics and similarity metrics for each approach. Bold indicates the best performance. Architectural Metrics CMod CiD BCP 93.0 98.6 34.6 82.9 89.6 33.7 73.6 71.3 41.1 38.5 93.8 42.3 42.6 58.9 26.6 83.1 97.9 45.5

Approach MicroAgent Base LLM Mono2Micro MonoEmbed CARGO MOSAIC

WS 89.2% 71.6% 31.1% 37.3% 21.1% 44.3%

Similarity Metrics 𝒕𝒉 𝒄𝒗𝒈 = 50% 𝒕𝒉 𝒄𝒗𝒈 = 75% 94.5% 75.7% 80.3% 55.3% 14.4% 3.3% 22.0% 0% 0% 0% 36.9% 22.5%

𝒕𝒉 𝒄𝒗𝒈 = 90% 53.0% 10.4% 0% 0% 0% 8.3%

Spring-Petclinic JPetstore

Benchmark Applications

Conference’17, July 2017, Washington, DC, USA

Acme Air 7ep-demo PartsUnlimited goodsKill PassJava microservices-platform youlai-mall gulimall

10

20

30

40 50 60 Weighted Similarity (%) MicroAgent Base LLM MonoEmbed Mono2Micro

70

80

90

100

MOSAIC CARGO

Figure 3: Per-application WS across methods. Answer to RQ1: MicroAgent achieves satisfying results in both architectural metrics and similarity metrics. Our tool demonstrates a 24.6% improvement in the weighted similarity, and a substantial 409.6% improvement in 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%). This implies MicroAgent produces decomposition results that are closer to the ground truth decomposition, which are of much higher quality.

4.3

RQ2: Performance of MicroAgent in Assigning Common Classes

Assigning common classes is one of the most error-prone aspects of dependency management in microservice decomposition, especially

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

in multi-domain scenarios where proper allocation is critical yet highly challenging. We compare how MicroAgent and baseline tools perform in this complex task. As shown in Table 4, the precision, recall, and F1 scores for each class-level decomposition approach are reported on average. MicroAgent shows the highest precision in identifying and assigning common classes, which is 3.4% higher than the best baseline Mono2Micro. Moreover, it demonstrates remarkable improvement in both recall and F1, which are 52.7% and 41.1% higher than the best baseline, respectively. These indicate that MicroAgent not only presents high recall in identifying necessary common classes that should be shared among partitions, but also precisely assigns the common classes to the corresponding microservice partitions. Table 4: Experiment results demonstrating the effects of common classes assignment. Bold indicates the best performance. Approach

Precision

Recall

F1

MicroAgent Base LLM Mono2Micro MonoEmbed

94.0% 82.7% 90.9% 43.7%

93.6% 61.3% 31.5% 13.4%

93.4% 66.2% 45.2% 19.9%

Answer to RQ2: MicroAgent showcases the highest precision and recall in common classes assignment. It notably improves the F1 score by 41.1%, indicating the effectiveness of our designs in MicroAgent for accurately identifying and properly distributing the common classes.

4.4

RQ3: Ablation Study of MicroAgent

To evaluate the contribution of each component in MicroAgent, we conduct an ablation study to assess their effectiveness. We mainly focus on four important settings: (1) without the dependency analysis context, (2) without specialized tools for Clustering Agent, (3) without specialized tools for Common Class Agent, and (4) without multi-agent framework (single agent with all tools provided). Table 5 demonstrates the ablation study results on average. When specialized tools are not provided for the Clustering Agent, it obtains the lowest score in BCP among these four settings. Meanwhile, the overall quality and accuracy of the decomposition declines compared with MicroAgent, as weighted similarity and 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%) deteriorate by 6.8% and 17.2%, respectively. Under the setting without specialized tools for Common Class Agent, all types of metrics fall consistently, the decrease is pronounced for the 𝑐2𝑐𝑐𝑣𝑔 when 𝑡ℎ𝑐𝑣𝑔 = 90%. It drops from 53.0% to 38.3%, representing a 27.7% decrease. Meanwhile, the weighted similarity decreases from 89.2% to 82.1% with F1 score drops from 93.4% to 92.0%. This indicates that the specialized tools for Common Class Agent contribute to both the common class metric and the overall decomposition quality. Omitting the dependency context also results in worse performance. There is an 10% decrease in weighted similarity from 89.2% to 80.2%, and a significant 27.7% drop in 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%) from 53.0% to 38.3%. Moreover, the F1 score also exhibits a decrease from 93.4% to 91.5%. These all show that the dependency context is crucial for a more accurate decomposition. We further evaluate a single-agent setting, where all tools are provided to one agent without the multi-agent workflow. This setting yields the most significant degradation: weighted similarity drops by 13.8% to 76.9%, and F1 decreases sharply from 93.4% to

Conference’17, July 2017, Washington, DC, USA

81.2%. This suggests that the multi-agent workflow is a critical component in MicroAgent. By decomposing the task into focused subtasks, each agent can concentrate on a specific scope without being overwhelmed by overlong context, whereas a single agent struggles to coordinate the full decomposition even when provided with the same set of tools. Table 5: Ablation study results of MicroAgent. Bold indicates the best performance. Setting MicroAgent w/o clustering tools w/o common class tools w/o dependency context single agent

Architecture Metrics CMod CiD BCP 93.0 98.6 34.6 91.9 93.6 29.4 92.2 93.3 32.6 92.0 94.6 32.9 91.1 93.6 33.4

WS 89.2% 83.1% 82.1% 80.2% 76.9%

Similarity Metrics 𝒕𝒉 𝒄𝒗𝒈 = 50% 𝒕𝒉 𝒄𝒗𝒈 = 75% 94.5% 75.7% 88.4% 75.0% 86.7% 71.8% 83.1% 65.6% 84.3% 59.9%

𝒕𝒉 𝒄𝒗𝒈 = 90% 53.0% 43.9% 38.3% 38.3% 40.1%

Common Class F1 93.4% 92.2% 92.0% 91.5% 81.2%

Answer to RQ3: The ablation study confirms the contribution of each component. Among all settings, replacing the multi-agent workflow with a single agent causes the largest performance deterioration. The specialized tools and dependency context each further contribute to the overall decomposition quality.

4.5

RQ4: Effects of Different LLMs

We select three commonly used LLM models to study how different backbone models generalize on MicroAgent. As introduced in section 4.1, they are Deepseek-V3.2, GPT-5.2, and Claude-Sonnet-4.5. Table 6 demonstrates the performance of MicroAgent with these different base models. As revealed by the similarity metrics, MicroAgent can consistently improve the accuracy and quality of decomposition across all the base models. MicroAgent enhances the weighted similarity by 15.1%-24.6%, and increases 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%) with an range of 185.5% to 409.6%. In terms of identifying and assigning common classes, MicroAgent outperforms the original base model by 30.0%-73.9% on average. Additionally, while the Claude base model surpasses the MicroAgent in 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 50%), MicroAgent clearly outperforms it in weighted similarity, F1, and 𝑐2𝑐𝑐𝑣𝑔 with 𝑡ℎ𝑐𝑣𝑔 = 90%. This suggests that Claude base model more often produces decompositions that are moderately aligned with the ground truth (above 50% similarity), whereas MicroAgent consistently delivers highly accurate results, achieving substantially more near-exact matches (above 90% similarity) and better overall performance. Also, we can notice that MicroAgent obtains the greatest improvement in weighted similarity and 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%) when applied to Deepseek-V3.2, and achieves the most enhancement in F1 for Claude-Sonnet-4.5 model. Table 6: Generalization of different LLMs with MicroAgent. Model Deepseek-V3.2 GPT-5.2 Claude-Sonnet-4.5

Approach MicroAgent Base LLM MicroAgent Base LLM MicroAgent Base LLM

Architecture Metrics CMod CiD BCP 93.0 98.6 34.6 82.9 89.6 33.7 93.6 98.0 31.8 82.3 91.7 30.3 93.0 98.3 34.2 85.8 90.9 25.1

WS 89.2% 71.6% 82.7% 70.0% 84.4% 73.3%

Similarity Metrics 𝒕𝒉 𝒄𝒗𝒈 = 50% 𝒕𝒉 𝒄𝒗𝒈 = 75% 94.5% 75.7% 80.3% 55.3% 90.9% 73.2% 84.1% 51.7% 86.3% 78.8% 93.2% 55.4%

𝒕𝒉 𝒄𝒗𝒈 = 90% 53.0% 10.4% 47.4% 16.6% 54.0% 16.3%

Common Class F1 93.4% 66.2% 91.5% 70.4% 92.7% 53.3%

Answer to RQ4: MicroAgent can consistently enhance the performance of the three LLM base models. It outperforms the base models in the weighted similarity by 15.1%-24.6%, and improves 𝑐2𝑐𝑐𝑣𝑔 (𝑡ℎ𝑐𝑣𝑔 = 90%) by 185.5%409.6%. This shows that MicroAgent can generalize well with different backbones of LLM.

Conference’17, July 2017, Washington, DC, USA

5

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

Case Study

Recall from Section 2 that when directly prompted with the repositorylevel context, the base LLM incorrectly assigned “OrderItemVo” to Cart Service and Order Service based on surface-level name similarity (Figure 1b). Moreover, traditional tools often neglect common class assignment, resulting in misplaced or missing allocations for shared classes. In this case study, we trace how MicroAgent handles the same application gulimall [11], focusing on four representative classes: “OrderItemVo”, “Query”, “SQLFilter”, and “RRException”. Domain identification and clustering. Instead of providing the full repository-level information that can cause hallucination and information overload, Domain Agent operates on compressed class summaries and correctly identifies eight business domains, including Order Service, Warehouse Service, and Member Service. Each domain is then handled by a dedicated Clustering Agent with domain-tailored context, which leverages codebase_semantic_search and get_related_class_list to collect domainspecific classes (e.g., “OrderServiceImpl” → Order Service, “WareSkuServiceImpl” → Warehouse Service). Part of the input for tool assign_common_class_list Part of the output from tool rank_dependency_entropy_and_ratio { "incoming_dependency_entropy": { "ranked_classes_by_incoming_entropy": [ ... { "class_name": "io.gulimall.utils.Query", "entropy": 1.8987, "incoming dependency_ratio": 53.0 }, { "class_name": "io.gulimall.vo.OrderItemVo", "entropy": 0.9183, "incoming dependency_ratio": +Infinity } ... } "USED_BY" : { "io.gulimall.service.ware.impl.WareSkuServiceImpl", "io.gulimall.vo.WareSkuLockVo", "io.gulimall.vo.order.OrderConfirmVo", "io.gulimall.service.order.impl.OrderServiceImpl” ... } "USED_BY" : { "io.gulimall.service.member.impl.MemberServiceImpl", "io.gulimall.service.order.impl.OrderItemServiceImpl", "io.gulimall.service.ware.impl.WareSkuServiceImpl", ... }

Corresponding dependency output from tool get_class_relation_and_code

"io.gulimall.utils.Query": { "domains": ["Order Service", "Warehouse Service", "Member Service", ... ], "relationship_type": "incoming" }, "io.gulimall.xss.SQLFilter": { "domains": [ ], "relationship_type": "incoming" }, "io.gulimall.exception.RRException": { "domains": [ ], "relationship_type": "incoming" }

Call tool assign_common_class_list "io.gulimall.utils.Query": { "domains": ["Order Service", "Warehouse Service", "Member Service", ... ], "relationship_type": "incoming" }, "io.gulimall.xss.SQLFilter": { "domains": ["Order Service", "Warehouse Service", "Member Service", ... ], "relationship_type": "incoming" }, "io.gulimall.exception.RRException": { "domains": ["Order Service", "Warehouse Service", "Member Service", ... ], "relationship_type": "incoming" }

Query

SQLFilter

five domains of “Query” are propagated first to “SQLFilter”, then to “RRException” (Figure 4, right). The final assignment for all four traced classes matches the ground truth, illustrating how the combination of multi-granularity context, code-level dependency analysis, and entropy-guided tools produces practical decomposition results.

6

Threats to Validity

Internal Validity. (1) Uncertainty of LLM Outputs: The inherent non-determinism of LLMs may lead to variability in their outputs, which can impact the reproducibility of our experimental results. To mitigate this issue, we set the temperature parameter to 0 to ensure deterministic outputs as much as possible. (2) Assumption of Known Microservice Partition Count: We assume the target number of microservices is provided as known information in the input, following the assumptions of previous works [24, 32, 45] in microservice decomposition. However, in some real-world decomposition scenarios, the target microservice count may not always be predetermined and may be adjusted based on actual requirements. The topic of finding the optimal number of microservices is out of the discussion scope in this paper. External Validity. In our evaluation, we focus on applications in Java. This is consistent with previous works in microservice decomposition, since Java has been a dominant language for web or enterprise application development [23]. For generalizability in different programming languages, our framework design is languageagnostic and can also be applied to other languages.

RRException

Part of the output from assign_common_class_list after propagation

Figure 4: Demonstration of case study in gulimall application. Common class identification and assignment. As shown on the left of Figure 4, the Common Class Agent invokes tool rank_dependency_entropy_and_ratio, which flags both “OrderItemVo” and “Query” with high incoming dependency entropy, indicating they are depended on by multiple domains. Unlike base LLMs, which rely on the name similarity between “OrderItemVo” and “CartItemVo” and assign the former class to Cart Service, the agent calls get_class_relation_and_code to inspect actual usage context (shown in Figure 1b): “OrderItemVo” is created during order submission in Order Service and consumed by “WareSkuServiceImpl” for inventory locking in Warehouse Service. Based on this codelevel evidence, the agent correctly assigns “OrderItemVo” to Order Service and Warehouse Service, matching the ground truth. Similarly, “Query”, a pagination utility referenced across domains, is assigned to five domains including Order Service, Warehouse Service, and Member Service. Propagation for transitive dependencies. “Query” depends on “SQLFilter”, which in turn depends on “RRException”. Neither class has direct cross-domain references, making them invisible to baseline approaches that only track first-order dependencies. The agent invokes assign_common_class_list, which propagates domain assignments along the dependency chain (Algorithm 1): the

7

Related Work

Most existing microservice decomposition studies follow a common paradigm: they construct a relation graph from a monolith and apply clustering or community detection to optimize architectural metrics. These works can be categorized based on the information they utilize as follows. The most common heuristics utilize code analysis to build application graphs, representing code elements as nodes and their relationships (e.g., function calls or control flow) as edges [24, 30, 32, 38, 45]. These works typically utilize static analysis [30, 45], dynamic analysis [32, 38], or combining both [24, 50] to construct a method-level or class-level dependency graph before clustering. However, due to the intrinsic limitations of static analysis, works that solely use static analysis typically have sparse coverage of code elements and fail to scale for larger cases. Moreover, dynamic analysis often requires a large collection of use cases, which can be difficult to achieve. Due to these drawbacks, the graphs obtained by the program analysis techniques are usually sparse and incomplete, leading to poor clustering effects. To address the limitations of program analysis, semantic analysis is often integrated to learn graph representations before clustering. Previous works [21, 41, 50, 54] rely on Term Frequency or embedding models, which capture surface-level semantics like class name similarity but overlook code context and business logic. Other approaches require per-application training for class embeddings [27]. Similarly, recent LLM-based methods either treat LLMs as simple tokenizers [22] or demand data-intensive fine-tuning [49] before deployment. Additionally, Some methods leverage external information for graph representation, including database schemas [48]

MicroAgent: Context-Augmented Multi-Agent Framework for Automatic Microservice Decomposition

and version history [41]. However, existing approaches generally lack sufficient understanding of the overall business logic, resulting in poor microservice decomposition performance in real-world scenarios. In contrast, MicroAgent leverages tailored multi-granularity context and decomposition-oriented tools to achieve deep comprehension of both codebase and business logic.

8

Conclusions

We propose MicroAgent, a context-augmented multi-agent framework for microservice decomposition. To address the inefficiencies of manual methods and existing automatic tools, MicroAgent divides decomposition into five subtasks, equips specialized agents with tailored multi-granularity context, and provides decompositionoriented tools aligned with microservice principles. Across benchmark datasets, MicroAgent achieves 89.2% average decomposition accuracy, improving over the best baseline by 24.6%, and reaches a 93.4% F1 score on common-class identification and assignment, surpassing baselines by 41.1%. These results show that MicroAgent can produce accurate and practical microservice partitions.

References [1] BLUEPERF — github.com. https://github.com/blueperf. [2] Claude Sonnet 4.5 — anthropic.com. https://www.anthropic.com/claude/sonnet. [3] Context Engineering — blog.langchain.com. https://blog.langchain.com/contextengineering-for-agents. [4] Context Engineering - What it is, and techniques to consider — LlamaIndex - Build Knowledge Assistants over your Enterprise Data — llamaindex.ai. https://www.llamaindex.ai/blog/context-engineering-what-it-is-andtechniques-to-consider. [5] GitHub - 7ep/demo: A demonstration of a web application with tests — github.com. https://github.com/7ep/demo. [6] GitHub - blueperf/acmeair-monolithic-java: This version of Acme air is redesigned removing hardcoded components to WXS and also optimized for Cloud Data Services — github.com. https://github.com/blueperf/acmeair-monolithicjava. [7] GitHub - jackson0714/passjava-platform. https://github.com/Jackson0714/ PassJava-Platform. [8] GitHub - microsoft/PartsUnlimitedMRP: This application uses entirely open source software including Linux, Java, Apache, and MongoDB which creates a web front end, an order service, and an integration service. — github.com. https://github.com/microsoft/PartsUnlimitedMRP. [9] GitHub - microsoft/PartsUnlimitedMRPmicro: A microservices-based application using entirely open source software including Docker, Kubernetes, Java, Apache, Hystrix, and MongoDB which creates a web front end and 5 supporting microservices. — github.com. https://github.com/microsoft/PartsUnlimitedMRPmicro. [10] GitHub - mybatis/jpetstore-6: A web application built on top of MyBatis 3, Spring 3 and Stripes — github.com. https://github.com/mybatis/jpetstore-6. [11] GitHub - niceseason/gulimall-learning. https://github.com/NiceSeason/gulimalllearning. [12] GitHub - spring-petclinic/spring-petclinic-microservices: Distributed version of Spring Petclinic built with Spring Cloud — github.com. https://github.com/springpetclinic/spring-petclinic-microservices. [13] GitHub - spring-projects/spring-petclinic: A sample Spring-based application — github.com. https://github.com/spring-projects/spring-petclinic. [14] GitHub - techa03/goodskill. https://github.com/techa03/goodsKill. [15] GitHub - youlaitech/youlai-mall. https://github.com/youlaitech/youlai-mall. [16] GitHub - zlt2000/microservices-platform. https://github.com/zlt2000/ microservices-platform. [17] Introducing GPT-5.2 — openai.com. https://openai.com/index/introducing-gpt5-2/. [18] JavaParser - Home — javaparser.org. https://javaparser.org/. [19] sentence-transformers/all-MiniLM-L6-v2 · Hugging Face — huggingface.co. https: //huggingface.co/sentence-transformers/all-MiniLM-L6-v2. [20] Abgaz, Y., McCarren, A., Elger, P., Solan, D., Lapuz, N., Bivol, M., Jackson, G., Yilmaz, M., Buckley, J., and Clarke, P. Decomposition of monolith applications into microservices architectures: A systematic review. IEEE Transactions on Software Engineering 49, 8 (2023), 4213–4242. [21] Al-Debagy, O., and Martinek, P. A microservice decomposition method through using distributed representation of source code. Scalable Computing: Practice and Experience 22, 1 (2021), 39–52.

Conference’17, July 2017, Washington, DC, USA

[22] Alsayed, A. S., Dam, H. K., and Nguyen, C. Microdec: Leveraging large language models for microservice decomposition. [23] Antoniadis, A., Filippakis, N., Krishnan, P., Ramesh, R., Allen, N., and Smaragdakis, Y. Static analysis of java enterprise applications: frameworks and caches, the elephants in the room. In Proceedings of the 41st ACM SIGPLAN conference on programming language design and implementation (2020), pp. 794–807. [24] Assunção, W. K., Colanzi, T. E., Carvalho, L., Pereira, J. A., Garcia, A., de Lima, M. J., and Lucena, C. A multi-criteria strategy for redesigning legacy features as microservices: An industrial case study. In 2021 IEEE International conference on software analysis, evolution and reengineering (SANER) (2021), IEEE, pp. 377–387. [25] Carvalho, L., Garcia, A., Assunção, W. K., de Mello, R., and de Lima, M. J. Analysis of the criteria adopted in industry to extract microservices. In 2019 IEEE/ACM Joint 7th International Workshop on Conducting Empirical Studies in Industry (CESI) and 6th International Workshop on Software Engineering Research and Industrial Practice (SER&IP) (2019), IEEE, pp. 22–29. [26] Dean, J., Grove, D., and Chambers, C. Optimization of object-oriented programs using static class hierarchy analysis. In European conference on object-oriented programming (1995), Springer, pp. 77–101. [27] Desai, U., Bandyopadhyay, S., and Tamilselvam, S. Graph neural network to dilute outliers for refactoring monolith application. In Proceedings of the AAAI conference on artificial intelligence (2021), vol. 35, pp. 72–80. [28] Evans, E. Domain-driven design: tackling complexity in the heart of software. Addison-Wesley Professional, 2004. [29] Fan, A., Gokkaya, B., Harman, M., Lyubarskiy, M., Sengupta, S., Yoo, S., and Zhang, J. M. Large language models for software engineering: Survey and open problems. In 2023 IEEE/ACM International Conference on Software Engineering: Future of Software Engineering (ICSE-FoSE) (2023), IEEE, pp. 31–53. [30] Filippone, G., Mehmood, N. Q., Autili, M., Rossi, F., and Tivoli, M. From monolithic to microservice architecture: an automated approach based on graph clustering and combinatorial optimization. In 2023 IEEE 20th International Conference on Software Architecture (ICSA) (2023), IEEE, pp. 47–57. [31] III, S. M. F. What led amazon to its own microservices architecture, May 2021. [32] Kalia, A. K., Xiao, J., Lin, C., Sinha, S., Rofrano, J., Vukovic, M., and Banerjee, D. Mono2micro: an ai-based toolchain for evolving monolithic enterprise applications to a microservice architecture. In Proceedings of the 28th ACM joint meeting on european software engineering conference and symposium on the foundations of software engineering (2020), pp. 1606–1610. [33] Lewis, J., and Fowler, M. Microservices: a definition of this new architectural term. MartinFowler. com 25, 14-26 (2014), 12. [34] Lewis, P., Perez, E., Piktus, A., Petroni, F., Karpukhin, V., Goyal, N., Küttler, H., Lewis, M., Yih, W.-t., Rocktäschel, T., et al. Retrieval-augmented generation for knowledge-intensive nlp tasks. Advances in neural information processing systems 33 (2020), 9459–9474. [35] Li, J., Wang, M., Zheng, Z., and Zhang, M. Loogle: Can long-context language models understand long contexts? arXiv preprint arXiv:2311.04939 (2023). [36] Li, T., Zhang, G., Do, Q. D., Yue, X., and Chen, W. Long-context llms struggle with long in-context learning. arXiv preprint arXiv:2404.02060 (2024). [37] Liu, A., Mei, A., Lin, B., Xue, B., Wang, B., Xu, B., Wu, B., Zhang, B., Lin, C., Dong, C., et al. Deepseek-v3. 2: Pushing the frontier of open large language models. arXiv preprint arXiv:2512.02556 (2025). [38] Liu, B., Xiong, J., Ren, Q., Tyszberowicz, S., and Yang, Z. Log2ms: a framework for automated refactoring monolith into microservices using execution logs. In 2022 IEEE International Conference on Web Services (ICWS) (2022), IEEE, pp. 391– 396. [39] Lutellier, T., Chollak, D., Garcia, J., Tan, L., Rayside, D., Medvidović, N., and Kroeger, R. Measuring the impact of code dependencies on software architecture recovery techniques. IEEE Transactions on Software Engineering 44, 2 (2017), 159–181. [40] Martin, R. C. The single responsibility principle. https://blog.cleancoder.com/ uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html. [41] Mazlami, G., Cito, J., and Leitner, P. Extraction of microservices from monolithic software architectures. In 2017 IEEE International Conference on Web Services (ICWS) (2017), IEEE, pp. 524–531. [42] Microsoft. Using domain analysis to model microservices. https: //learn.microsoft.com/en-us/azure/architecture/microservices/model/domainanalysis. [43] Newman, S. Building microservices: designing fine-grained systems. " O’Reilly Media, Inc.", 2021. [44] Ni, A., Allamanis, M., Cohan, A., Deng, Y., Shi, K., Sutton, C., and Yin, P. Next: Teaching large language models to reason about code execution. arXiv preprint arXiv:2404.14662 (2024). [45] Nitin, V., Asthana, S., Ray, B., and Krishna, R. Cargo: Ai-guided dependency analysis for migrating monolithic applications to microservices architecture. In Proceedings of the 37th IEEE/ACM International Conference on Automated Software Engineering (2022), pp. 1–12.

Conference’17, July 2017, Washington, DC, USA

Zishan Su, Junjie Huang, Shiwen Shan, Xingyan Chen, Hui Zeng, Yuxin Su, Yanlin Wang, and Michael R. Lyu

[46] Quattrocchi, G., Cocco, D., Staffa, S., Margara, A., and Cugola, G. Cromlech: Semi-automated monolith decomposition into microservices. IEEE Transactions on Services Computing 17, 2 (2024), 466–481. [47] Richardson, C. Microservices patterns: with examples in Java. Simon and Schuster, 2018. [48] Romani, Y., Tibermacine, O., and Tibermacine, C. Towards migrating legacy software systems to microservice-based architectures: a data-centric process for microservice identification. In 2022 IEEE 19th International Conference on Software Architecture Companion (ICSA-C) (2022), IEEE, pp. 15–19. [49] Sellami, K., and Saied, M. A. Monoembed: Enhancing llm representations for monolith to microservices decomposition through contrastive learning. Empirical Software Engineering 31, 1 (2026), 11. [50] Sellami, K., Saied, M. A., Ouni, A., and Abdalkareem, R. Combining static and dynamic analysis to decompose monolithic application into microservices. In International Conference on Service-Oriented Computing (2022), Springer, pp. 203– 218. [51] Shannon, C. E. A mathematical theory of communication. The Bell system technical journal 27, 3 (1948), 379–423.

[52] Taibi, D., and Lenarduzzi, V. On the definition of microservice bad smells. IEEE software 35, 3 (2018), 56–62. [53] Thönes, J. Microservices. IEEE software 32, 1 (2015), 116–116. [54] Trabelsi, I., Abdellatif, M., Abubaker, A., Moha, N., Mosser, S., EbrahimiKahou, S., and Guéhéneuc, Y.-G. From legacy to microservices: A type-based approach for microservices identification using machine learning and semantic analysis. Journal of Software: Evolution and Process 35, 10 (2023), e2503. [55] Uchitelle, E. M. Upgrading github from rails 3.2 to 5.2, Jul 2021. [56] Vernon, V. Implementing domain-driven design. Addison-Wesley, 2013. [57] Wang, Y., Bornais, S., and Rubin, J. Microservice decomposition techniques: An independent tool comparison. In Proceedings of the 39th IEEE/ACM International Conference on Automated Software Engineering (2024), pp. 1295–1307. [58] Xu, J., Luo, X., Pan, X., Li, Y., Pei, W., and Xu, Z. Alleviating the sample selection bias in few-shot learning by removing projection to the centroid. Advances in neural information processing systems 35 (2022), 21073–21086. [59] Zhang, Z., Wang, C., Wang, Y., Shi, E., Ma, Y., Zhong, W., Chen, J., Mao, M., and Zheng, Z. Llm hallucinations in practical code generation: Phenomena, mechanism, and mitigation. Proceedings of the ACM on Software Engineering 2, ISSTA (2025), 481–503.