{"id":28438319,"url":"https://github.com/azurecosmosdb/multi-agent-spring-ai","last_synced_at":"2026-01-29T11:38:16.246Z","repository":{"id":286830764,"uuid":"962706046","full_name":"AzureCosmosDB/multi-agent-spring-ai","owner":"AzureCosmosDB","description":"A sample for multi-agent orchestration in Java using Azure Cosmos DB with Spring AI","archived":false,"fork":false,"pushed_at":"2025-04-09T11:48:21.000Z","size":16043,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-06T01:05:59.898Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AzureCosmosDB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-08T14:52:28.000Z","updated_at":"2025-06-04T04:39:30.000Z","dependencies_parsed_at":"2025-04-08T15:57:18.919Z","dependency_job_id":null,"html_url":"https://github.com/AzureCosmosDB/multi-agent-spring-ai","commit_stats":null,"previous_names":["azurecosmosdb/multi-agent-spring-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AzureCosmosDB/multi-agent-spring-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2Fmulti-agent-spring-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2Fmulti-agent-spring-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2Fmulti-agent-spring-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2Fmulti-agent-spring-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AzureCosmosDB","download_url":"https://codeload.github.com/AzureCosmosDB/multi-agent-spring-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2Fmulti-agent-spring-ai/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262452073,"owners_count":23313373,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-06T01:05:58.674Z","updated_at":"2026-01-29T11:38:16.240Z","avatar_url":"https://github.com/AzureCosmosDB.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Multi-agent Java sample with Spring AI and Azure Cosmos DB\n\nInspired by OpenAI Swarm and LangGraph - a sample personal shopping AI Chatbot that can help with product enquiries, making sales, and refunding orders by transferring to different agents for those tasks.\n\nFeatures:\n- **Multi-agent**: the sample implements a custom multi-agent orchestration framework using [Spring AI](https://docs.spring.io/spring-ai/reference/) and [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview) as building blocks. \n- **Transactional data management**: agents interact with the planet scale [Azure Cosmos DB database service](https://learn.microsoft.com/azure/cosmos-db/introduction) using [Spring AI tool calling](https://docs.spring.io/spring-ai/reference/api/tools-migration.html) to store transactional user and product operational data, implemented via [Spring Data](https://spring.io/projects/spring-data). \n- **Retrieval Augmented Generation (RAG)**: the sample uses [vector search](https://learn.microsoft.com/azure/cosmos-db/nosql/vector-search) in Azure Cosmos DB with powerful [DiskANN index](https://www.microsoft.com/en-us/research/publication/diskann-fast-accurate-billion-point-nearest-neighbor-search-on-a-single-node/?msockid=091c323873cd6bd6392120ac72e46a98) to serve product enquiries from the same database that is used for transactions. Implemented via the [Spring AI vector store plugin for Azure Cosmos DB](https://docs.spring.io/spring-ai/reference/api/vectordbs/azure-cosmos-db.html).\n- **Long term chat memory persistence**: the sample implements Spring AI's `ChatMemory` interface to store and manage long term chat memory for each user session in Azure Cosmos DB.\n- **Multi-tenant/user session storage**: [Hierarchical Partitioning](https://learn.microsoft.com/azure/cosmos-db/hierarchical-partition-keys) is used in Azure Cosmos DB to store and manage each user session, this is integrated into the UI. A \"default\" `tenantId` is used, and the user's local IP address is capatured as the `userId`.\n- **UI**: front end is built as a single-page application (SPA) using HTML, CSS, and JavaScript located in the resources/static folder. The UI talks to REST API endpoints exposed by the backend Spring Boot application.\n\n\n## UI demo\n\n![Demo](./media/demo.gif)\n\n## Overview\n\nThe personal shopper example includes 3 agents to handle various customer service requests, and an orchestrator for initial routing. The agents are implemented using [Spring AI](https://docs.spring.io/spring-ai/reference/) framework to interact with the Azure OpenAI API. The agents are designed to be modular and can be easily extended or replaced with other implementations.\n\n1. **Product Agent**: Answers customer queries from the products container using [Retrieval Augmented Generation (RAG)](https://learn.microsoft.com/azure/cosmos-db/gen-ai/rag).\n2. **Refund Agent**: Manages customer refunds, requiring both user ID and item ID to initiate a refund.\n3. **Sales Agent**: Handles actions related to placing orders, requiring both user ID and product ID to complete a purchase.\n\n\n## Prerequisites\n\n- [Azure Developer CLI (azd)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) **(recommended for deployment)**\n- [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) (required by azd)\n- [Maven](https://maven.apache.org/install.html) 3.8.1 or later\n- [Java 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or later\n\n\u003e **Note:** All Azure resources (Cosmos DB, OpenAI, Managed Identity, etc.) are provisioned automatically using Bicep via `azd up`. No manual portal setup required.\n\n\n## Setup \u0026 Deployment (ACD/azd)\n\nClone the repository:\n\n```shell\ngit clone https://github.com/TheovanKraay/multi-agent-spring-ai.git\ncd multi-agent-spring-ai\n```\n\n### 1. Authenticate to Azure\n\n```shell\naz login\nazd auth login\n```\n\n### 2. Provision all Azure resources (ACD/azd)\n\nRun the following to deploy all infrastructure (Cosmos DB, OpenAI, Managed Identity, etc.) to a new environment:\n\n```shell\nazd up\n```\n\nYou will be prompted for a location (e.g. eastus) and an environment name (e.g. dev, test, prod, etc). This will:\n\n- Create a new resource group and all required Azure resources using Bicep (see `infra/`)\n- Deploy Cosmos DB with vector search enabled, OpenAI with correct models, and assign RBAC\n- Auto-detect your Azure user and set the OWNER tag\n- **Generate `src/main/resources/application.properties` with the correct endpoints and deployment names for your environment**\n\n\u003e **Tip:** You can deploy to multiple environments (e.g. dev, test, prod) by running `azd up` with different environment names.\n\n### 3. Build the application\n\n```shell\nmvn clean package -DskipTests\n```\n\n### 4. Run the application\n\n```shell\njava -jar target/multi-agent-spring-ai-cosmos-1.0-exec.jar\n```\n\n### 5. Load sample data\n\n```shell\njava -jar target/multiagent-dataloader.jar\n```\n\n### 6. Test the app\n\n- Swagger UI: http://localhost:8080/swagger-ui/index.html\n- Web UI: http://localhost:8080\n- CLI: `java -jar target/multiagent-cli.jar`\n\n---\n\n## About `application.properties`\n\n- The file `src/main/resources/application.properties` is **auto-generated** by the `azd up` postprovision hook with the correct values for your environment.\n- The file is **gitignored**. Do not commit secrets or environment-specific values.\n- An example template is provided as `application.properties.example`.\n- To run locally without azd, copy the example and fill in your own values.\n\n---\n\n## Azure Credential Delegation (ACD) and RBAC\n\nThis sample uses [DefaultAzureCredential](https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#authenticate-a-user-assigned-managed-identity-with-defaultazurecredential) for all Azure SDK authentication. The Bicep and azd deployment will:\n\n- Assign a managed identity to the app\n- Grant RBAC data plane access to Cosmos DB and OpenAI\n- Tag all resources with the OWNER (auto-detected from your Azure account)\n\n**No connection strings or keys are required.**\n\nIf you need to run locally as a different user, ensure you have the correct RBAC roles assigned in the Azure Portal or via CLI.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fmulti-agent-spring-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazurecosmosdb%2Fmulti-agent-spring-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fmulti-agent-spring-ai/lists"}