Chat Agent Demo

ChatAgent

一个基于 Claude Agent SDK 构建的全栈对话应用 Demo，展示如何使用 Anthropic 官方 Agent SDK 构建具有流式响应、工具调用和多模态能力的 AI 应用。

注意：本项目是 Claude Agent SDK 的演示项目，旨在帮助开发者快速了解和上手 SDK 的核心功能。

Demo

alt text

✨ 功能特性

• 🚀 流式响应 - 实时逐字显示 AI 回复，提供流畅的用户体验
• 🔧 工具调用 - 支持 Agent 调用外部工具完成复杂任务
• 🖼️ 多模态输入 - 支持文本和图片混合输入
• 💬 多轮对话 - 完整的上下文管理，支持连续对话
• 📁 会话管理 - 支持创建、切换、删除多个独立会话
• ⏹️ 中断生成 - 支持随时停止 AI 响应生成
• 📝 Markdown 渲染 - 支持代码高亮、数学公式 (KaTeX)、Mermaid 图表
• 💾 数据持久化 - SQLite 存储聊天记录，支持历史查看

技术架构

┌─────────────────┐     WebSocket      ┌─────────────────┐
│                 │ ◄────────────────► │                 │
│  React 前端     │                    │  FastAPI 后端   │
│  (TypeScript)   │     REST API       │  (Python)       │
│                 │ ◄────────────────► │                 │
└─────────────────┘                    └────────┬────────┘
                                                │
                                                ▼
                                       ┌─────────────────┐
                                       │ Claude Agent SDK│
                                       │   (Anthropic)   │
                                       └─────────────────┘

后端技术栈

• Python 3.11+ + FastAPI - 异步 Web 框架
• Claude Agent SDK - Anthropic 官方 Agent SDK
• SQLite + aiosqlite - 异步数据持久化
• uv - 现代 Python 包管理器

前端技术栈

• React 19 + TypeScript - 类型安全的前端框架
• Vite 7 - 快速构建工具
• Tailwind CSS 4 + shadcn/ui - 现代化 UI
• react-markdown - Markdown 渲染（支持 GFM、数学公式、代码高亮）
• Mermaid - 图表渲染

快速开始

环境要求

• Python 3.11+
• Node.js 18+
• pnpm
• uv
• Anthropic API Key

启动后端

cd backend
cp .env.example .env
# 编辑 .env 填入 ANTHROPIC_API_KEY

uv sync
uv run uvicorn main:app --reload --host 0.0.0.0 --port 3001

启动前端

cd frontend
pnpm install
pnpm dev

访问 http://localhost:5173 开始体验。

📁 项目结构

ChatAgent/
├── backend/                    # Python FastAPI 后端
│   ├── main.py                # 应用入口
│   ├── pyproject.toml         # Python 依赖配置
│   └── app/
│       ├── config.py          # 全局配置（系统提示词、工具列表等）
│       ├── core/
│       │   ├── agent_session.py    # Claude Agent SDK 会话管理
│       │   └── session_manager.py  # WebSocket 会话和消息广播
│       ├── api/
│       │   ├── routes.py      # REST API 路由
│       │   └── websocket.py   # WebSocket 端点
│       └── services/
│           └── chat_store.py  # SQLite 数据库 CRUD
│
└── frontend/                   # React TypeScript 前端
    ├── package.json           # Node.js 依赖配置
    └── src/
        ├── components/
        │   ├── chat/          # ChatContainer, ChatMessage, ChatInput
        │   └── sidebar/       # ChatSidebar
        ├── hooks/
        │   ├── useChat.ts     # WebSocket 管理和消息处理
        │   └── useChatList.ts # 聊天列表管理
        └── services/
            └── api.ts         # REST API 调用

🔌 WebSocket 消息协议

客户端 → 服务器：

服务器 → 客户端：

⚙️ 配置说明

Agent 配置

后端配置位于 backend/app/config.py：

SYSTEM_PROMPT = "..."      # Claude 系统提示词
ALLOWED_TOOLS = [...]      # 允许的工具列表
MAX_TURNS = 100            # 最大对话轮数

MCP 服务器配置

MCP (Model Context Protocol) 服务器配置位于 backend/data/mcp_servers.json（参考 backend/data/mcp_servers.example.json）。支持 stdio 和 HTTP 两种类型：

{
  "mcpServers": {
    "server_name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-xxx"],
      "env": {},
      "allowedTools": ["tool1", "tool2"]
    },
    "http_server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "API_KEY": "your-api-key"
      },
      "allowedTools": ["tool1", "tool2"]
    }
  }
}

配置字段说明：

常用 MCP 服务器示例：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
      "allowedTools": ["read_file", "write_file", "list_directory"]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "your-api-key"
      },
      "allowedTools": ["resolve-library-id", "get-library-docs"]
    }
  }
}

相关资源

• Claude Agent SDK 官方文档
• Anthropic API 文档

License

MIT