{"id":24810564,"url":"https://github.com/azure-samples/aspire-semantic-kernel-creative-writer","last_synced_at":"2025-10-13T12:31:12.935Z","repository":{"id":271765127,"uuid":"914486088","full_name":"Azure-Samples/aspire-semantic-kernel-creative-writer","owner":"Azure-Samples","description":"A creative writing multi-agent solution to help users write articles using Aspire and Semantic Kernel","archived":false,"fork":false,"pushed_at":"2025-06-10T12:58:03.000Z","size":1056,"stargazers_count":58,"open_issues_count":6,"forks_count":37,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-10T13:45:00.732Z","etag":null,"topics":["agents","ai-azd-templates","aspire","azd-templates","azure","azure-ai-search","azureopenai","bing","llm","multi-agents","openai","sample","semantic-kernel"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","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/Azure-Samples.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-09T17:32:03.000Z","updated_at":"2025-05-22T05:53:25.000Z","dependencies_parsed_at":"2025-05-28T15:23:33.378Z","dependency_job_id":"aeeed798-7a77-4d90-bc61-69fd63d4e4d7","html_url":"https://github.com/Azure-Samples/aspire-semantic-kernel-creative-writer","commit_stats":null,"previous_names":["ricardoniepel/aspire-semantic-kernel-creative-writer","azure-samples/aspire-semantic-kernel-creative-writer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Azure-Samples/aspire-semantic-kernel-creative-writer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Faspire-semantic-kernel-creative-writer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Faspire-semantic-kernel-creative-writer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Faspire-semantic-kernel-creative-writer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Faspire-semantic-kernel-creative-writer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azure-Samples","download_url":"https://codeload.github.com/Azure-Samples/aspire-semantic-kernel-creative-writer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azure-Samples%2Faspire-semantic-kernel-creative-writer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015056,"owners_count":26085643,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["agents","ai-azd-templates","aspire","azd-templates","azure","azure-ai-search","azureopenai","bing","llm","multi-agents","openai","sample","semantic-kernel"],"created_at":"2025-01-30T12:17:15.458Z","updated_at":"2025-10-13T12:31:12.930Z","avatar_url":"https://github.com/Azure-Samples.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n---\npage_type: sample\nlanguages:\n- azdeveloper\n- bicep\n- csharp\n- typescript\nproducts:\n- ai-services\n- azure\n- azure-cognitive-search\n- azure-container-apps\n- azure-openai\n- dotnet\n- dotnet-aspire\nurlFragment: aspire-semantic-kernel-creative-writer\nname: \"Creative Writing Assistant: Working with Agents using Semantic Kernel and .NET Aspire\"\ndescription: \"Comprehensive example of a multi-agent chat application built with .NET Aspire, Semantic Kernel, React and Vite, and the `@microsoft/ai-chat-protocol` package.\"\n---\n--\u003e\n\n# Creative Writing Assistant: Working with Agents using Semantic Kernel and .NET Aspire (C#)\n\nThis project is an alternative to the python version at \u003chttps://github.com/Azure-Samples/contoso-creative-writer\u003e.\n\nIt is a comprehensive example of a chat application built with .NET Aspire, Semantic Kernel, and the `@microsoft/ai-chat-protocol` package. The frontend of the application is developed using React and Vite.\n\nUnderneath it uses an Azure AI Foundry hub \u0026 project, Azure AI Agent Service with a standard agent setup, Bing Search and Azure AI Search for grounding.\n\n- [Features](#features)\n- [Getting Started](#getting-started)\n  - [Prerequisites for running experiments](#prerequisites-for-running-experiments)\n  - [Try it out (experimentation phase)](#try-it-out-experimentation-phase)\n- [Local Development](#local-development)\n  - [Prerequisites for local development](#prerequisites-for-local-development)\n  - [Running the app](#running-the-app)\n  - [Evaluating results](#evaluating-results)\n    - [Running the Evaluation Tests](#running-the-evaluation-tests)\n    - [Generating the Evaluation report](#generating-the-evaluation-report)\n- [Azure Deployment](#azure-deployment)\n  - [Prerequisites for deployment](#prerequisites-for-deployment)\n  - [Instructions](#instructions)\n- [Sample Product Data](#sample-product-data)\n- [Guidance](#guidance)\n  - [Region Availability](#region-availability)\n  - [Costs](#costs)\n  - [Security](#security)\n- [Resources](#resources)\n- [Credits](#credits)\n- [Important Security Notice](#important-security-notice)\n- [License](#license)\n\n## Features\n\nThe application consists of 2 main projects:\n\n- `ChatApp.WebApi`: This is a .NET Web API that handles chat interactions, powered by .NET Aspire and Semantic Kernel. It provides endpoints for the chat frontend to communicate with the chat backend. The `@microsoft/ai-chat-protocol` package is used to handle chat interactions, including streaming and non-streaming requests. For normal chat completion both can be used, to trigger the creative writer only streaming is possible.\n\n- `ChatApp.React`: This is a React app that provides the user interface for the chat application. It is built using Vite, a modern and efficient build tool. It uses the `@microsoft/ai-chat-protocol` package to handle chat interactions, allowing for flexible communication with the chat backend.\n\nThe app also includes a class library project, ChatApp.ServiceDefaults, that contains the service defaults used by the service projects.\n\nIn addition it has two **.NET Interactive Notebooks** inside the `./experiments/` to show a simple WriterReviewer scenario and also the full version of the CreativeWritingAssistant outside of a real system.\n\n![App preview](./images/app_preview.png)\n\n![Agents](./images/agents_architecture.png)\n\n## Getting Started\n\nThe first step for getting started with this template are the notebooks which can be used as local experiments.\n\n![Notebook preview](./images/notebook_preview.png)\n\n### Prerequisites for running experiments\n\n- .NET 9 SDK\n- VSCode\n  - [Polyglot Notebooks Extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode)\n- [Azure Developer CLI (azd)](https://aka.ms/install-azd)\n\n### Try it out (experimentation phase)\n\nOpen the notebooks under `./experiments/` and follow their instructions.\n\n## Local Development\n\n### Prerequisites for local development\n\n- .NET 9 SDK\n- VSCode or Visual Studio 2022 17.12\n- [Node.js 22](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n- [Azure CLI (az)](https://aka.ms/install-azcli)\n- [Azure Developer CLI (azd)](https://aka.ms/install-azd)\n\n### Running the app\n\nIf using Visual Studio, open the solution file `ChatApp.sln` and launch/debug the `ChatApp.AppHost` project.\n\nIf using the .NET CLI, run `dotnet run` from the `ChatApp.AppHost` directory.\n\nFor more information on local provisioning of Aspire applications, refer to the [Aspire Local Provisioning Guide](https://learn.microsoft.com/en-us/dotnet/aspire/deployment/azure/local-provisioning).\n\n\u003e To utilize Azure resources (e.g. OpenAI) in your local development environment, you need to provide the necessary configuration values.  \n\u003e \u003chttps://learn.microsoft.com/en-us/dotnet/aspire/azure/local-provisioning#configuration\u003e\n\nExample to add into a `appsettings.Development.json` in the `ChatApp.AppHost` directory:\n\n``` json\n{\n  \"Azure\": {\n    \"SubscriptionId\": \"\u003cYour subscription id\u003e\",\n    \"AllowResourceGroupCreation\": true,\n    \"ResourceGroup\": \"\u003cValid resource group name\u003e\",\n    \"Location\": \"swedencentral\",\n    \"CredentialSource\": \"InteractiveBrowser\"\n  }\n}\n```\n\nIf you want to use existing Azure resource, put their endpoints below the Azure section:\n\n```json\n{\n  \"Azure\": {\n    \"SubscriptionId\": \"\u003cYour subscription id\u003e\",\n    \"AllowResourceGroupCreation\": true,\n    \"ResourceGroup\": \"\u003cValid resource group name\u003e\",\n    \"Location\": \"swedencentral\",\n    \"CredentialSource\": \"InteractiveBrowser\"\n  },\n  \"ConnectionStrings\": {\n    \"openAI\": \"https://\u003clorem\u003e.openai.azure.com/\",\n    \"vectorSearch\": \"https://\u003clorem\u003e.search.windows.net\"\n  }\n}\n```\n\n### Evaluating results\n\nCreative Writer Assistant uses evaluators to assess application response quality.  \nThe 4 metrics the evaluators in this project assess are **Coherence, Fluency, Relevance and Groundedness**.\n\nTo understand what is being evaluated open the `.\\src\\data\\test\\eval_inputs.json` file.  \nObserve that 3 examples of research, product and assignment context are stored in this file as different scenarios.  \nThis data will be sent to the API so that each example will have the evaluations run and will **incoperate all of the context, research, products, and final article when grading the response**.\n\n#### Running the Evaluation Tests\n\n1. Make sure the Creative Writer application is configured and able to run on your local machine before running the tests.  \n   The tests will call into the Creative Writer APIs to collect AI responses using an .NET Aspire test host.\n2. The evaluation process will use the same Azure OpenAI model deployment which is used by the main application.\n3. Run the tests from Visual Studio, VS Code, or `dotnet test`.\n\n#### Generating the Evaluation report\n\n1. Navigate into the `src\\ChatApp.EvaluationTests` folder\n2. Update your dotnet tools by running\n\n    ```shell\n    dotnet tool restore\n    ```\n\n3. Run the aieval report command to generate a report file.\n\n    ```shell\n    dotnet aieval report --path .\\bin\\Debug\\net9.0\\cache --output .\\report.html\n    ```\n\n4. Open the `report.html` file in your web browser.\n\n![AI Evaluations](./images/ai_evaluations.png)\n\n## Azure Deployment\n\n![Architecture](./images/container_architecture.png)\n\n### Prerequisites for deployment\n\n- [Azure CLI (az)](https://aka.ms/install-azcli)\n- [Azure Developer CLI (azd)](https://aka.ms/install-azd)\n- [Docker Desktop](https://www.docker.com/products/docker-desktop/)\n\n### Instructions\n\nNavigate into `./ChatApp.AppHost/`.\n\n1. Sign in to your Azure account. You'll need to login to both the Azure Developer CLI and Azure CLI:\n\n    i. First with Azure Developer CLI\n\n    ```shell\n    azd auth login\n    ```\n\n    ii. Then sign in with Azure CLI\n\n    ```shell\n    az login --use-device-code\n    ```\n\n2. Provision the resources and deploy the code:\n\n    ```shell\n    azd up\n    ```\n    \u003e Disclaimer: Azure AI Service is currently in preview as well as the Semantic Kernel Agent SDKs we are leveraging in this project.\n\n    This project uses `gpt-4o` and `Azure AI Agent Service` which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/en-us/azure/ai-services/agents/concepts/model-region-support#azure-openai-models) and select a region during deployment accordingly.  \n    We recommend using *Sweden Central* for this project.\n\n## Sample Product Data\n\nTo load sample product data into Azure AI Search as vector store, use the notebook inside `./src/data/`.\n\n## Guidance\n\n### Region Availability\n\nThis template uses `gpt-4o` and `text-embedding-3-large` which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and select a region during deployment accordingly\n\n- we recommend using eastus2 or swedencentral\n\n### Costs\n\nYou can estimate the cost of this project's architecture with [Azure's pricing calculator](https://azure.microsoft.com/pricing/calculator/)\n\n### Security\n\nThis template has [Managed Identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) and Key Vault built in to eliminate the need for developers to manage credentials. Applications can use managed identities to obtain Microsoft Entra tokens without having to manage any credentials. Additionally, we have added a [GitHub Action tool](https://github.com/microsoft/security-devops-action) that scans the infrastructure-as-code files and generates a report containing any detected issues. To ensure best practices in your repo we recommend anyone creating solutions based on our templates ensure that the [Github secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning) setting is enabled in your repos.\n\n## Resources\n\n- [Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/overview/)\n- [Semantic Kernel Agent Framework Documentation](https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/?pivots=programming-language-csharp)\n- [Aspire Documentation](https://learn.microsoft.com/en-us/dotnet/aspire/)\n- [Chat Protocol Documentation](https://learn.microsoft.com/en-us/dotnet/aspire/ai-chat-protocol/)\n\n## Credits\n\n- Initially based on [Aspire Sample Application](https://github.com/Azure-Samples/aspire-semantic-kernel-basic-chat-app)\n- Idea from [Creative Writing Assistant: Working with Agents using Prompty (Python Implementation)](https://github.com/Azure-Samples/contoso-creative-writer)\n\n## Important Security Notice\n\nThis template, the application code and configuration it contains, has been built to showcase Microsoft Azure specific services and tools. We strongly advise our customers not to make this code part of their production environments without implementing or enabling additional security features.  \n\nFor a more comprehensive list of best practices and security recommendations for Intelligent Applications, [visit our official documentation](https://learn.microsoft.com/en-us/azure/well-architected/ai/application-design).\n\n## License\n\nThis project is licensed under the terms of the MIT license. See the `LICENSE.md` file for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure-samples%2Faspire-semantic-kernel-creative-writer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazure-samples%2Faspire-semantic-kernel-creative-writer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazure-samples%2Faspire-semantic-kernel-creative-writer/lists"}