# AgentDesk

Apache-licensed AI help desk in Go and Next.js: RAG answers, answerability gate, human handoff, tickets.

AgentDesk is a self-hosted customer support system where an AI agent answers first from a knowledge base, refuses when retrieval is weak, hands off to human agents, and opens tickets, with an embeddable widget and Telegram, WeChat, and Zalo channels. Configuration is a single config/config.yaml; models are any OpenAI-compatible provider. The backend exposes an HTTP API for conversations, messages, customers, and webhooks, and an internal MCP tool server at /api/mcp.

Alternative to: Intercom, Zendesk

- Capabilities: adaptable, operable
- Vertical: support-bookkeeping
- Shape: business-app
- Form factor: web-app
- Execution model: hybrid
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/huabeitech/agent-desk (Apache-2.0), 222 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/huabeitech--agent-desk.html
- JSON: apps/huabeitech--agent-desk.json

## Use it when

- we want an AI-first support widget that only answers from our own docs and escalates to a person when it cannot
- we need a self-hosted help desk under a permissive license that we can point at any OpenAI-compatible model, including a local one

## Gotchas

- Documentation site returned 403/404 during analysis; README is the working reference
- Default language zh-CN and default admin password ChangeMe123!
- Needs Qdrant (or a LanceDB build with native libs) even for local trials
- 222 stars and a single vendor org; verify users beyond the Reddit launch

## Editions

- Free (self-hosted): Free, open source
  - source: https://github.com/huabeitech/agent-desk
  - container: docker compose up -d --build

## Adaptable: make it yours

Effort: config-only (3 things to edit)

Copy config/config.example.yaml to config/config.yaml (docker/agent-desk.yaml for Compose). An SMB sets language (defaults to zh-CN), server.port and cors.allowedOrigins, db.type and dsn, auth.passwordLoginEnabled and tokenTTLHours, customerSession.secret, storage.default (local or oss), vectorDB.type (qdrant or lancedb), mcp.servers, and oidc. Model providers, embedding models, prompts, knowledge bases, and agent-to-skill bindings are configured in the dashboard, not files. Change the default admin password before exposing it.

- Env vars: none
- Config files: config/config.yaml, config/config.example.yaml, docker/agent-desk.yaml
- Prompt files: none
- Accounts you'll need: an OpenAI-compatible model provider (or a local server); Alibaba Cloud OSS (optional storage); Telegram, WeChat, or Zalo developer accounts (optional channels)

## Operable: what an agent can drive

Operability: gui. Interface: gui at https://github.com/huabeitech/agent-desk (published by the builder, local).

### Reach (none coverage)

- Start a support conversation and send customer messages: not reachable. /api/conversation and /api/message exist (internal/bootstrap/server.go) behind ExternalUserMiddleware customer-session tokens, but no docs describe them; docs site returns 403 and README has no API section
- Register and look up customers: not reachable. /api/customer/session_exchange and /api/dashboard/customer routes exist in source only; undocumented
- Receive events by webhook: not reachable. /api/webhooks/org-sync and dos-org-sync are org-directory sync hooks in source, not documented event webhooks
- Create and move tickets: not reachable. /api/dashboard/ticket routes exist behind the dashboard Bearer token; undocumented
- Manage knowledge bases and FAQs: not reachable. dashboard-only routes; undocumented
- Hand off to a human agent: not reachable. runtime decision inside the agent flow; no documented external call
- Configure AI agents, models, and skills: not reachable. model configuration and agent binding are dashboard screens
- Connect Telegram, WeChat, Zalo: not reachable. internal/handlers/third holds inbound channel webhooks; setup is configuration
- Drive AgentDesk from an external agent over MCP: not reachable. app.Any('/api/mcp') mounts mcps.NewHTTPHandler for the runtime's own tools; not documented as an inbound interface or its auth

## Code stack

- Languages: Go, TypeScript
- Frameworks: Gin, GORM, Next.js 16, React 19, shadcn/ui
- Package manager: go modules, pnpm
- Database: SQLite, MySQL, PostgreSQL, Qdrant, LanceDB
- Hosting target: Docker Compose, single Go binary

## Model stack

- Providers: any OpenAI-compatible provider
- Models: none
- Keys you need (names only): none
- Prompts live in: AI Agent configuration (dashboard UI)
- Tools: Skills, MCP tool servers configured under mcp.servers

## Skills

contributor: Repo carries contributor-facing development skills (git commit, release versioning) for working on the app. [contributor tooling, not adopter-facing]
- Paths: .codex/skills/*/SKILL.md

## Evidence and confidence

- formFactor: README: Docker Compose starts agent-desk on 8083 with mysql and qdrant; admin dashboard and customer chat pages (confidence 0.9)
- executionModel: README AI Agent Workflow: fixed orchestration (retrieve, answerability gate, LLM reply, handoff) (confidence 0.9)
- operability: internal/services/auth_service.go: POST /api/auth/login issues an access token used as 'Authorization: Bearer <token>' (or ?accessToken=) on /api/dashboard/*; /api/conversation and /api/message use a customer-session token from session_exchange. None of this is documented: agent-desk.huabei.pro/docs returns 403, README links only Docker, widget, and model-provider pages, and no API page exists in the repo tree. (confidence 0.8)
- effort: README: cp config/config.example.yaml config/config.yaml; example file lists server, db, auth, storage, vectorDB, mcp, oidc sections (confidence 0.85)
- editions: README: open-source, self-hosted; no paid edition mentioned (confidence 0.8)
- active: gh api: pushed 2026-09-02, 222 stars
- reach:  (confidence 0.75)

## Open questions

- If the Builder publishes API docs (login token, dashboard endpoints, /api/mcp auth), re-verify as official/api: the code surface is there
- Public API docs (agent-desk.huabei.pro/docs) content: endpoint list and channel keys
- Any hosted or paid edition from huabei

## Sources

- https://github.com/huabeitech/agent-desk (sourcing:support-bookkeeping:community)
- https://agent-desk.huabei.pro (sourcing:support-bookkeeping:github)