{"id":51410408,"url":"https://github.com/ahmettugur/agentic-customer-support-bot","last_synced_at":"2026-07-04T14:30:53.494Z","repository":{"id":356331175,"uuid":"1224513794","full_name":"ahmettugur/agentic-customer-support-bot","owner":"ahmettugur","description":"Agentic customer support system using .NET 10 + Microsoft Agent Framework (MAF). Features 6-agent orchestration (Planning + Specialists + Response), deterministic reasoning pipeline, HITL approval gates, compound query decomposition, and full observability via reasoning traces.","archived":false,"fork":false,"pushed_at":"2026-06-03T02:58:54.000Z","size":21338,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-03T04:26:19.734Z","etag":null,"topics":["agent-orchestration","agentic-ai","ai-agents","chatbot","hitl","human-in-the-loop","maf","microsoft-agents-framework","multi-agent","multi-agent-systems","react-patterns","server-sent-events","sse","streaming","tool-calling","tracing"],"latest_commit_sha":null,"homepage":"","language":"C#","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/ahmettugur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/agents.md","dco":null,"cla":null}},"created_at":"2026-04-29T11:02:55.000Z","updated_at":"2026-05-06T08:52:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ahmettugur/agentic-customer-support-bot","commit_stats":null,"previous_names":["ahmettugur/agentic-customer-support-bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ahmettugur/agentic-customer-support-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmettugur%2Fagentic-customer-support-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmettugur%2Fagentic-customer-support-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmettugur%2Fagentic-customer-support-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmettugur%2Fagentic-customer-support-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmettugur","download_url":"https://codeload.github.com/ahmettugur/agentic-customer-support-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmettugur%2Fagentic-customer-support-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35125718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"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":["agent-orchestration","agentic-ai","ai-agents","chatbot","hitl","human-in-the-loop","maf","microsoft-agents-framework","multi-agent","multi-agent-systems","react-patterns","server-sent-events","sse","streaming","tool-calling","tracing"],"created_at":"2026-07-04T14:30:50.704Z","updated_at":"2026-07-04T14:30:53.481Z","avatar_url":"https://github.com/ahmettugur.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agentic Müşteri Destek Botu\n\n**Microsoft Agents Framework (MAF)** ve **.NET 10** üzerine inşa edilmiş, agentik mimarili bir müşteri destek chatbot'u.\n\nSistem, uzmanlaşmış LLM ajanlarından oluşan bir takımı orkestrasyon mantığıyla çalıştırır. Temel yetenekler:\n\n- **Ürün sorgusu**, **sipariş takibi**, **sipariş oluşturma** ve **şikayet kaydı** işlemleri\n- **Structured reasoning** — Her adımda açık akıl yürütme ve kendi kendini doğrulama\n- **Human-in-the-Loop (HITL)** — Kritik işlemlerde insan onayı\n- **Gerçek zamanlı streaming** — SSE üzerinden canlı yanıt akışı\n\n---\n\n## İçindekiler\n\n- [Demo](#demo)\n- [Genel Bakış](#genel-bakış)\n- [Mimari](#mimari)\n- [Ajan Takımı](#ajan-takımı)\n- [Teknoloji Yığını](#teknoloji-yığını)\n- [Başlangıç](#başlangıç)\n- [API Endpoint'leri](#api-endpointleri)\n- [Human-in-the-Loop (HITL)](#human-in-the-loop-hitl)\n- [Değerlendirme ve Test](#değerlendirme-ve-test)\n- [Proje Yapısı](#proje-yapısı)\n- [Dokümantasyon](#dokümantasyon)\n- [Lisans](#lisans)\n\n---\n\n## 🎬 Demo\n\nhttps://github.com/user-attachments/assets/9cf6ba41-7fa1-49da-ad9b-251ea4b3ae65\n\n\u003e **Not:** Video GitHub'da görüntülenemiyorsa, dosyayı `docs/media/1767601282559.mp4` konumunda bulabilirsiniz.\n\n---\n\n## Genel Bakış\n\nBu proje, müşteri desteği için **çok ajanlı orkestrasyon** desenini gösterir. Tek bir monolitik LLM çağrısı yerine, sistem yapılandırılmış bir iş akışı içinde işbirliği yapan 6 uzman ajan kullanır:\n\n1. **PlanningAgent** — Kullanıcı sorgusunu doğru uzmana yönlendirir.\n2. **Uzman Ajanlar** (Product, Order, Complaint) — Alan görevlerini tool çağrıları ile gerçekleştirir.\n3. **ResponseAgent** — Self-critique (öz-eleştiri) ile nihai yanıtı sentezler.\n\nTemel yetenekler:\n\n- **Yapılandırılmış reasoning** — Araç çağrısı öncesi kontrol (`preToolCheck`) ve sonrası yansıtma (`postToolReflection`) (ReAct + Self-Reflection desenleri)\n- **SSE streaming** — Gerçek zamanlı ajan adım görünürlüğü\n- **Human-in-the-Loop (HITL)** — Yan etkili tool'lar (sipariş oluşturma, şikayet kaydı) için açık admin onayı\n- **Reasoning trace store** — Hata ayıklama ve denetim için\n- **Entity verification** — Bellek içi veritabanına karşı doğrulama\n- **Deterministic sanity checking** — Reasoning tutarlılığı için 8 kurallı deterministik doğrulama\n- **Compound query orkestrasyonu** (Faz 4b) — Çoklu niyetli kullanıcı mesajları için\n- **Evaluation runner** — YAML tabanlı senaryo testleri\n- **Canlı admin devralma** — Herhangi bir oturumu bot modundan anlık olarak insan moduna geçirme\n\n---\n\n## Mimari\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│                        FRONTEND (wwwroot/)                          │\n│         index.html + chat-ui.js   — SSE streaming UI              │\n└─────────────────────────────┬────────────────────────────────────┘\n                              │ HTTP / SSE\n┌─────────────────────────────▼────────────────────────────────────┐\n│                     ENDPOINTS (Minimal API)                      │\n│   ChatEndpoints │ SessionEndpoints │ TraceEndpoints │ Admin    │\n└───────┬───────────────────┬──────────────────┬───────────┬─────────┘\n        │                   │                  │           │\n        ▼                   ▼                  ▼           ▼\n┌───────────────┐  ┌────────────────┐  ┌─────────────┐  ┌────────┐\n│ ReasoningSvc  │  │ CustomerSupp.  │  │ TraceStore  │  │ Admin  │\n│  (o-series)   │─▶│ Team           │  │ (in-memory) │  │ (HITL) │\n└───┬───────────┘  │ (6 agents +    │  └─────────────┘  └────────┘\n    │              │  ChatManager   │\n    │              │  + Phase 4b     │\n    │              │  orchestration) │\n    │              └────────┬───────┘\n    │                       │\n    │         ┌─────────────┴─────────────┐\n    │         ▼                           ▼\n    │  ┌───────────────┐          ┌───────────────┐\n    │  │ PromptService │          │ ContextPipe.  │\n    │  │ (MD loader)   │          │ (providers)   │\n    │  └───────────────┘          └───────┬───────┘\n    │                                     │\n    │              ┌──────────────────────┴───────────┐\n    │              ▼                                  ▼\n    │     CustomerContext                  ConversationSummary\n    │     (FakeDatabase)                   (LLM summary)\n    │\n    │  ┌─────────────────────────────────────────────────────────┐\n    └─▶│         Deterministic Reasoning Helpers                 │\n       │   EntityVerifier        (ID extract + DB verify)        │\n       │   ReasoningSanityChecker(8-rule post-validation)        │\n       └─────────────────────────────────────────────────────────┘\n                                  │\n                                  ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                      ALTYAPI                                    │\n│  OpenAI Chat Client (gpt-4o)  │  ReasoningChatClient (o4-mini)  │\n│  FakeDatabase (Product/Order/Complaint)  │  IdExtractor (regex) │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Ajan Takımı\n\n| Ajan | Rol | Tool'lar | Yapılandırılmış Çıktı |\n|------|-----|----------|-----------------------|\n| **PlanningAgent** | Niyet tespiti ve yönlendirme | — | `PlanningResult` |\n| **ProductInquiryAgent** | Ürün sorgusu (salt-okunur) | `product_inquiry_tool` | `SpecialistReasoning` |\n| **OrderPlacementAgent** | Sipariş oluşturma (yan etkili) | `order_placement_tool` | `SpecialistReasoning` |\n| **OrderInquiryAgent** | Sipariş durumu sorgusu | `order_status_tool`, `get_last_order_tool`, `get_all_orders_tool` | `SpecialistReasoning` |\n| **ComplaintAgent** | Şikayet kaydı | `complaint_registration_tool` | `SpecialistReasoning` |\n| **ResponseAgent** | Nihai yanıt + self-critique | — | `ResponseCritique` |\n\nHer uzman ajan, aşağıdaki **4 adımlı alt-bileşen zincirini** izler:\n\n1. **Input Prep** — Sistem prompt'u + bağlam + reasoning ipucu + entity extraction ipucu\n2. **LLM Reasoning** — `preToolCheck` JSON bloğu üretir\n3. **Tool Execution** — `canProceed=true` ise MAF tool'u çağırır\n4. **Reflection + Kullanıcı Mesajı** — `postToolReflection` + kullanıcıya yönelik Türkçe mesaj\n\n---\n\n## Teknoloji Yığını\n\n| Katman | Teknoloji |\n|--------|-----------|\n| Framework | .NET 10 (ASP.NET Core Minimal API) |\n| Ajan Framework | Microsoft Agents Framework (MAF) 1.1.0 |\n| AI Soyutlamaları | `Microsoft.Extensions.AI` |\n| LLM Sağlayıcı | OpenAI (`gpt-5.4`, `o4-mini`) |\n| OpenAPI | `Microsoft.AspNetCore.OpenApi` 10.0.5 |\n| Serileştirme | System.Text.Json (camelCase enum string'leri) |\n| YAML Ayrıştırma | YamlDotNet 16.2.1 |\n| Arayüz | Vanilla HTML/JS/CSS (SSE streaming chat UI) |\n\n---\n\n## Başlangıç\n\n### Gereksinimler\n\n- [.NET 10 SDK](https://dotnet.microsoft.com/download)\n- **OpenAI API key**\n\n### Yapılandırma\n\n`CustomerSupportBot/appsettings.json` dosyasını düzenleyin:\n\n```json\n{\n  \"OpenAI\": {\n    \"ApiKey\": \"sk-...\",\n    \"Model\": \"gpt-5.4\",\n    \"ReasoningModel\": \"o4-mini\",\n    \"ReasoningEffort\": \"medium\"\n  }\n}\n```\n\n### Çalıştırma\n\n```bash\ndotnet run --project CustomerSupportBot/CustomerSupportBot.csproj\n```\n\nAPI `https://localhost:\u003cport\u003e` adresinde başlar ve chat arayüzü `wwwroot/index.html` üzerinden sunulur.\n\n### Hızlı API Testi\n\n```bash\ncurl -X POST http://localhost:\u003cport\u003e/chat/ \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"ORD-1 siparişim nerede?\", \"sessionId\": null}'\n```\n\n---\n\n## API Endpoint'leri\n\n| Endpoint | Metod | Açıklama |\n|----------|-------|----------|\n| `/chat/` | `POST` | Non-streaming chat |\n| `/chat/stream` | `POST` | SSE streaming chat |\n| `/sessions/{sessionId}` | `GET` | Oturum durumu ve mesajlar |\n| `/traces/{traceId}` | `GET` | Bir çalıştırma için reasoning trace'i |\n| `/traces/latest/{sessionId}` | `GET` | Oturumun en son trace'i |\n| `/evaluation/run` | `POST` | YAML senaryo testlerini çalıştır |\n| `/approvals/pending` | `GET` | Bekleyen HITL onaylarını listele |\n| `/approvals/{id}/approve` | `POST` | Bir tool çağrısını onayla |\n| `/approvals/{id}/reject` | `POST` | Bir tool çağrısını reddet |\n| `/escalations` | `GET` | Yükseltmeleri listele |\n| `/escalations/{id}/resolve` | `POST` | Bir yükseltmeyi çöz |\n\nTam API referansı için [`docs/api.md`](docs/api.md) dosyasına bakın.\n\n---\n\n## Human-in-the-Loop (HITL)\n\nBot iki HITL modunu destekler:\n\n1. **Onay Kuyruğu** — Yan etkili tool'lar (sipariş oluşturma, şikayet kaydı) çalıştırılmadan önce açık admin onayı gerektirir. Zaman aşımı ve otomatik onay politikaları `appsettings.json` üzerinden yapılandırılabilir.\n2. **Canlı Devralma** — Admin, herhangi bir aktif oturumu gerçek zamanlı olarak **Bot** modundan **İnsan** moduna geçirebilir, son kullanıcıyla doğrudan konuşabilir ve tekrar bot'a devredebilir.\n\nAdmin paneline `/admin.html` adresinden erişilebilir.\n\n---\n\n## Değerlendirme ve Test\n\nSenaryo tabanlı değerlendirme, `EvaluationRunner` tarafından yürütülür. Her senaryo canlı iş akışına karşı çalıştırılır ve her kriter için geçti/kaldı raporu sunulur.\n\n```bash\ncurl -X POST http://localhost:\u003cport\u003e/evaluation/run\n```\n\n---\n\n## Proje Yapısı\n\n```\nCustomerSupportBot/\n├── Program.cs                    # DI + endpoint mapping\n├── appsettings.json              # OpenAI, WorkflowGuards, HITL config\n│\n├── Agents/\n│   ├── CustomerSupportTeam.cs    # 6 MAF ajanı + workflow builder\n│   └── CustomerSupportChatManager.cs  # GroupChatManager (seçim + sonlandırma)\n│\n├── Endpoints/\n│   ├── ChatEndpoints.cs          # POST /chat + /chat/stream (SSE)\n│   ├── SessionEndpoints.cs       # Oturum sorguları\n│   ├── TraceEndpoints.cs         # Reasoning trace erişimi\n│   ├── EvaluationEndpoints.cs    # Test koşturucu\n│   ├── AdminEndpoints.cs         # HITL onayları + yükseltmeler\n│   └── SseWriter.cs              # SSE event yardımcısı\n│\n├── Evaluation/\n│   ├── EvaluationRunner.cs\n│   ├── CriteriaEvaluator.cs\n│   └── ScenarioModels.cs\n│\n├── Models/\n│   ├── ChatRequest.cs / ChatResponse.cs\n│   ├── PlanningResult.cs\n│   ├── ReasoningResult.cs / ReasoningStep.cs / ReasoningIssue.cs\n│   ├── SpecialistReasoning.cs\n│   ├── ResponseCritique.cs\n│   ├── ReasoningTrace.cs\n│   ├── VerifiedEntities.cs\n│   ├── ToolResult.cs\n│   ├── FakeDatabase.cs           # Bellek içi Product / Order / Complaint deposu\n│   └── ...\n│\n├── Prompts/\n│   ├── agents/                   # 7 ajan instruction prompt'u (markdown)\n│   │   ├── planning-agent.md\n│   │   ├── product-inquiry-agent.md\n│   │   ├── order-placement-agent.md\n│   │   ├── order-inquiry-agent.md\n│   │   ├── complaint-agent.md\n│   │   ├── human-handoff-agent.md\n│   │   └── response-agent.md\n│   └── services/                 # Reasoning ipuçları, entity extraction ipuçları, vb.\n│\n├── Services/\n│   ├── ReasoningService.cs       # o-series yapılandırılmış reasoning\n│   ├── ReasoningSanityChecker.cs # 8 kural deterministik doğrulama\n│   ├── EntityVerifier.cs         # ReAct-lite entity grounding\n│   ├── RevisionService.cs        # Yanıt revizyon döngüsü\n│   ├── PromptService.cs          # Markdown prompt yükleyici\n│   ├── ContextPipeline.cs        # Bağlam toplama\n│   ├── InMemorySessionManager.cs # Oturum + konuşma deposu\n│   ├── InMemoryApprovalQueue.cs  # HITL onay kuyruğu\n│   ├── InMemoryChatBridge.cs     # Canlı devralma mesaj köprüsü\n│   └── ...\n│\n├── Tools/\n│   └── (Ajanlar tarafından kullanılan AIFunction tool'ları)\n│\n└── wwwroot/\n    ├── index.html                # Chat arayüzü\n    ├── admin.html                # Admin / HITL paneli\n    ├── traces.html               # Trace görüntüleyici\n    ├── js/                       # chat-ui.js, admin.js, vb.\n    └── css/\n```\n\n---\n\n## Dokümantasyon\n\n`docs/` dizini, Türkçe olarak yazılmış detaylı teknik dokümantasyon içerir:\n\n| Doküman | İçerik |\n|---------|--------|\n| [`docs/architecture.md`](docs/architecture.md) | Üst seviye mimari, bileşen haritası, istek yaşam döngüsü |\n| [`docs/runtime.md`](docs/runtime.md) | Uygulama nasıl çalışır? Kurulum, başlangıç sırası, SSE kanalları, admin paneli, sorun giderme |\n| [`docs/agents.md`](docs/agents.md) | Ajan sorumlulukları, alt-bileşen zinciri, iç anatomi |\n| [`docs/api.md`](docs/api.md) | Tam HTTP + SSE event referansı |\n| [`docs/workflow.md`](docs/workflow.md) | İş akışı fazları, compound query orkestrasyonu |\n| [`docs/patterns.md`](docs/patterns.md) | Tasarım desenleri: ReAct, Self-Reflection, Chain-of-Thought, sub-agent vs sub-component |\n| [`docs/reasoning.md`](docs/reasoning.md) | Reasoning servisi, sanity check'ler, entity doğrulama, yapılandırılmış çıktı |\n| [`docs/developer-guide.md`](docs/developer-guide.md) | Ajan, tool ve prompt ekleme için geliştirici rehberi |\n| [`docs/reference.md`](docs/reference.md) | Sınıf/arayüz kontratları (C# API referansı) |\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmettugur%2Fagentic-customer-support-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmettugur%2Fagentic-customer-support-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmettugur%2Fagentic-customer-support-bot/lists"}