DomainAgent

English version · 中文版本

DomainAgent is a full-stack reference template for building domain-focused AI Agent applications.

Typhoon analysis is the first working domain example. The project is not intended to be limited to typhoon-related use cases. It demonstrates how a real business domain can be connected to a reusable Agent runtime, MCP capabilities, knowledge retrieval, authentication, streaming interfaces, and operational foundations.

Introduction

The goal of DomainAgent is to make it practical to build a complete AI application for a specific business domain without rebuilding the entire frontend and backend architecture from scratch.

The project is organized around a simple idea:

• the Agent runtime, conversation flow, authentication, persistence, streaming protocol, audit trail, and operational endpoints should be reusable;
• domain capabilities should be replaceable through tools, MCP servers, data adapters, and knowledge sources;
• a new domain should be able to reuse the application shell and runtime while changing its own terminology, tools, data sources, prompts, and user workflows.

Typhoon is therefore used as a concrete reference implementation rather than as the boundary of the architecture. The repository aims to be both a useful typhoon Agent application and a practical starting point for building other domain-oriented Agent products.

This is an evolving reference implementation. It provides the foundation and several working patterns for a migratable domain framework.

Quick Start

Prerequisites

• Node.js 20 or newer
• npm
• PostgreSQL with the pgvector extension enabled
• An LLM API key for chat

Start the complete local stack

From the repository root:

cd server
npm install
Copy-Item .env.example .env

Edit server/.env and set at least:

• DATABASE_URL
• BETTER_AUTH_SECRET
• DEEPSEEK_API_KEY

MCP capabilities are optional. The default MCP_SERVERS=auto discovers and starts all available built-in MCP servers. Set MCP_SERVERS=[] to start only the backend and frontend, or provide a JSON array to select specific capabilities, for example:

MCP_SERVERS=[{"id":"amap","url":"http://localhost:8102/mcp"}]

Configure the credentials required by the enabled capabilities: EMBEDDING_API_KEY and EMBEDDING_BASE_URL for rag, QWEATHER_API_KEY for typhoon, and AMAP_API_KEY for amap. When MCP_SERVERS=auto, capabilities whose required credentials are unavailable are skipped automatically. Then install the frontend dependencies and initialize the database:

cd ..\web
npm install

cd ..\server
npm run db:push
npm run seed
npm run dev:all

npm run dev:all starts the available local MCP servers selected by MCP_SERVERS, followed by the backend and the Next.js frontend. An unavailable optional MCP is reported in the log without stopping the core services.

Open the application at:

http://localhost:3000/typhoon-agent-web

The backend listens on http://localhost:8000. The example MCP servers use ports 8101, 8102, and 8103.

Technical Highlights

The following capabilities are currently implemented in the repository.

Full-stack application foundation

• Next.js frontend and Hono backend in one repository
• TypeScript across the frontend, backend, Agent runtime, and MCP examples
• Backend HTTP routes with Zod-based request validation
• Clear separation between application modules, Agent runtime code, database access, and example integrations

Agent runtime and tool use

• AI SDK-based model execution with multi-step tool calling
• Bounded Agent execution with a maximum step limit
• Typed Agent trace events for model output, tool calls, tool results, errors, and terminal states
• Conversation, message, session, and run persistence in PostgreSQL

MCP capability integration

• MCP tools connected through Streamable HTTP
• Configuration-driven MCP server registration through MCP_SERVERS
• Three runnable example MCP servers for typhoon data, map and POI services, and vector knowledge retrieval
• Real-provider adapters with local mock paths for the example domain
• Server-side user identity injection and filtering of sensitive identity fields from tool input

Knowledge and document workflows

• PostgreSQL and pgvector-based knowledge storage and retrieval
• Embedding service integration through an OpenAI-compatible interface
• Text extraction for TXT, Markdown, PDF, and DOCX uploads
• Knowledge ingestion exposed through the RAG MCP capability

Authentication and data boundaries

• Better Auth cookie-based sessions
• Authentication middleware for protected API routes
• User-scoped conversations, Agent runs, audit events, and knowledge records
• Request identifiers and trace identifiers for correlating application activity

Streaming, audit, and runtime observability

• Server-Sent Events chat protocol for incremental text and Agent state updates
• Persisted Agent run events with a replay endpoint
• Initial idempotency-key and Agent lifecycle primitives for run creation
• Audit event persistence with sequence metadata, hash-chain fields, redaction versioning, and cost aggregation
• /livez, /readyz, and /healthz endpoints
• Graceful shutdown handling for the backend and the local multi-service development runner
• Frontend run-trace panel and history-oriented Agent interaction UI

Repository Layout

server/   Hono API, Agent runtime, database layer, auth, audit, and MCP examples
web/      Next.js application and domain-facing UI
Docs/     Architecture review and project documentation

The typhoon implementation is the reference domain. A future domain can reuse the shared application and runtime foundations while replacing the domain-specific MCP servers, tools, data adapters, prompts, and UI terminology.