by huabeitech
Open-source AI customer support system. AI-first support, human-ready operations.
# Add to your Claude Code skills
git clone https://github.com/huabeitech/agent-deskLast scanned: 6/8/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-08T08:55:39.227Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail · terms & refunds
English | 简体中文
An open-source AI Agent customer support system with knowledge-based answers, human handoff, ticket workflows, and self-hosted deployment.
Built for teams that need online support, knowledge-base Q&A, human collaboration, and service tracking in one system. It is not just an LLM inside a chat box; it is an AI Helpdesk foundation designed around real support operations.
Customer chat, agent workspace, knowledge base, model configuration, and AI Agent orchestration are managed in one system.

Customers can start a conversation from the web chat page. The AI Agent responds first with knowledge-grounded answers. When the user explicitly asks for a human, the system can start a handoff confirmation flow.

The support workspace includes conversation lists, message handling, AI-to-human handoff, agent replies, conversation tags, linked customers, and ticket context for daily support work.
| Knowledge Base FAQ | AI Agent Configuration |
|---|---|
![]() |
![]() |
The knowledge base stores FAQs, documents, and retrievable content. AI Agents can be bound to model configurations, knowledge bases, Skills, and tools to create support agents for specific scenarios.

Model configuration supports OpenAI-compatible providers. You can configure LLMs, embedding models, rerank models, context limits, output settings, timeout, retry behavior, and enablement state.
The fastest way to try the full stack is Docker Compose:
docker compose up -d --build
For the full English setup guide, see Docker Compose Quick Start.
To embed customer support on your website, see Web Widget Integration.
To connect OpenAI-compatible model providers, see Model Provider Configuration.
Compose starts:
agent-desk: application service on port 8083mysql: MySQL 8.4 with the mysql-data volumeqdrant: vector database with the qdrant-data volume, ports 6333 / 6334After startup, open:
http://localhost:8083/dashboardhttp://localhost:8083/dashboard/conversationshttp://localhost:8083/support/demohttp://localhost:8083/support/chatDefault administrator account:
adminChangeMe123!Before exposing the system to the public internet or a team environment, change the default administrator password and configure independent authentication, session, and model secrets.
1.26+20+pnpmcp config/config.example.yaml config/config.yaml
The default configuration uses:
data/app.dbhttp://127.0.0.1:8083127.0.0.1:6334If Qdrant is not running locally, start it with Docker:
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
Install frontend dependencies:
cd web
pnpm install
cd ..
Start backend and frontend development servers together:
make dev
Default development URLs:
http://localhost:3000/dashboardhttp://localhost:3000/dashboard/conversationshttp://localhost:3000/support/demohttp://localhost:3000/support/chatgithub.com/mlogclub/simple.
├── cmd/ # server / migration / generator / testdata
├── internal/
│ ├── bootstrap/ # startup, routes, database, and migration initialization
│ ├── builders/ # model / aggregate result to response DTO mapping
│ ├── handlers/ # dashboard / api / third HTTP handlers
│ ├── middleware/ # Gin middleware
│ ├── migration/ # idempotent data migrations
│ ├── models/ # GORM models
│ ├── repositories/ # data access layer
│ ├── services/ # business orchestration and transaction boundaries
│ ├── ai/ # LLM / RAG / Runtime / Skills / MCP
│ └── pkg/ # config / dto / enums / httpx / utils and shared packages
├── web/ # Next.js frontend project
│ ├── app/dashboard/ # admin dashboard and agent workspace
│ ├── app/support/ # customer integration and chat pages
│ ├── components/ # React components
│ ├── lib/ # API client, SDK source, and utilities
│ └── public/sdk/ # built embeddable SDK
├── config/ # configuration files
├── docker/ # Docker configuration
└── docs/ # documentation site
make dev # start backend and frontend development servers
make build # build the frontend SPA and current-platform Go binary into dist/
make build LANCEDB=1 # build the current-platform LanceDB binary into dist/
make release # build linux/darwin/windows release binaries into dist/
make release LANCEDB=1 # build LanceDB release binaries into dist/
make generator # run code generation
make enums # generate frontend enums
make help # show available make targets
flowchart TD
A[User starts a support request<br/>Web support entry / Open API] --> B[Create or match a conversation]
B --> C[Customer sends a message]
C --> D[Trigger AI Reply Runtime]
D --> E[Load conversation history / AI configuration]
E --> F[Retrieve from bound knowledge bases]
F --> G{Are retrieved chunks enough to answer?}
G -- No --> Z[Return knowledge fallback<br/>and recommend human support]
G -- Yes --> H[Prepare Skills / MCP Tools]
H --> I[Pass trusted knowledge context to the Agent]
I --> J{Direct reply?}
J -- Yes --> K[LLM generates a knowledge-grounded reply]
J -- No --> N{Call Graph / MCP Tool?}
N -- Yes --> O[Run Skill / Graph / MCP Tool]
O --> P{Need user confirmation?}
P -- No --> I
P -- Yes --> Q[Ask the user to confirm]
Q --> R{Confirmation result}
R -- Confirm handoff --> S[Move conversation to human handoff pool]
S --> T[Automatic or manual assignment]
T --> U[Agent workspace takeover]
U --> V{Need ticket tracking?}
V -- Yes --> W[Create or link a ticket]
V -- No --> X[Human agent continues handling]
W --> X
X --> Y[Resolve and close]
R -- Confirm ticket --> AA[Create a ticket from the current conversation]
AA --> I
R -- Cancel --> K
N -- No --> K
flowchart LR
A[Customer request] --> B[AI Agent handles first]
B --> C{Can the knowledge base answer?}
C -- Yes --> D[AI replies with trusted knowledge]
C -- No --> E[Fallback / recommend human support]
D --> F{Need a human?}
E --> G[Human takeover]
F -- No --> H[Conversation ends or data is retained]
F -- Yes --> G
G --> I[Agent workspace handles the case]
I --> J{Need follow-up tracking?}
J -- Yes --> K[Create / link a