Agentic Application Stack
Agentic 应用的技术栈分层：从用户界面到 Agent 引擎，每一层的职责、选型和工程边界。
#type / concept
#status / evergreen
#tech / ai
#tech / architecture
[!info] related notes
- 所属 MOC: AI Agent Application MOC
- 核心概念: AI Agent Application
- 各层入口: Chat UI, Backend For Frontend, AI Service
Agentic Application Stack
一句话定义
Agentic Application Stack 是构建 AI Agent 应用所需的完整技术栈分层，从用户界面到 Agent 引擎，每一层有明确的职责边界和选型考量。
它解决什么问题
很多团队在构建 AI Agent 应用时遇到的问题不是”能不能调通 API”，而是：
- 前端和后端的职责怎么划分？谁管 SSE？
- Python AI Service 需要直接查业务数据库吗？
- 工具注册和执行放在哪一层？
- 上下文组装在 Go 端还是 Python 端？
- 流式事件的协议怎么定义？
技术栈分层不清晰，会导致代码散落、职责混乱、难以维护。
核心原理
四层架构
┌─────────────────────────────────────────────────────┐
│ Layer 1: 用户交互层 (React) │
│ Chat UI · Tool Call UI · Approval UI · Artifact UI │
├─────────────────────────────────────────────────────┤
│ Layer 2: 业务编排层 (Go) │
│ Session · Message · Context Builder · SSE Gateway │
├─────────────────────────────────────────────────────┤
│ Layer 3: Agent 引擎层 (Python) │
│ Agent Runtime · Tool Registry · RAG · Memory │
├─────────────────────────────────────────────────────┤
│ Layer 4: 基础设施层 │
│ LLM Provider · Vector DB · Database · Object Store │
└─────────────────────────────────────────────────────┘各层职责边界
| 层 | 核心职责 | 不该做的事 |
|---|---|---|
| React 前端 | 渲染、交互、状态展示 | 不做业务逻辑、不直接调 LLM |
| Go 后端 | 会话管理、上下文组装、协议转换、权限 | 不做 Agent 推理、不直接查向量库 |
| Python AI Service | Agent 推理、工具执行、RAG、记忆 | 不直接查业务数据库、不管用户鉴权 |
| 基础设施 | 提供 LLM、向量存储、文件存储 | 不包含业务逻辑 |
层间通信协议
React ←→ Go: HTTP REST + SSE (流式)
Go ←→ Python: gRPC 或 HTTP + SSE (流式)
Python ←→ LLM: HTTP API (OpenAI/Anthropic 兼容协议)典型工程实现
一个请求的完整数据流
用户输入 "分析最近的销售趋势"
│
▼
[React] POST /api/chat/message
│
▼
[Go] Auth → Create Turn → ContextBuilder.Build()
│
▼
[Go] POST /ai-service/chat (携带 Context Bundle)
│
▼
[Python] AgentRuntime.start_run(context)
│
├── LLM 推理 → 决定调用 query_database
├── ToolExecutor.execute(query_database)
├── 结果回传 LLM
├── LLM 推理 → 决定调用 create_chart
├── ToolExecutor.execute(create_chart)
├── LLM 生成最终回复
│
▼
[Python] SSE stream → Go → React
│
▼
[React] 渲染: 文本 + 图表 + 工具调用状态技术选型参考
| 层 | 推荐技术栈 | 替代方案 |
|---|---|---|
| 前端 | React + Vercel AI SDK / assistant-ui | Next.js、Vue |
| 后端 | Go (Gin/Echo) + SSE | Node.js (Express/Fastify) |
| AI Service | Python (FastAPI) + LangGraph | TypeScript (Vercel AI SDK) |
| LLM | OpenAI API / Anthropic API | 自部署模型 |
| 向量库 | pgvector (MVP) → Qdrant/Milvus (规模化) | Pinecone、Weaviate |
| 数据库 | PostgreSQL | MySQL、MongoDB |
| 对象存储 | S3 / MinIO | 本地文件系统 |
| 可观测性 | OpenTelemetry + LangSmith/Langfuse | 自建 |
常见设计模式
1. BFF 模式 (Backend For Frontend)
Go 后端作为前端的专用后端，负责协议转换和上下文组装，不暴露 AI Service 的内部细节。
2. AI Service 独立部署
Python AI Service 作为独立服务，通过内部 API 与 Go 通信。好处是独立扩缩容、独立发布。
3. LLM Provider 抽象
AI Service 内部通过抽象层对接多个 LLM Provider，支持模型切换和 Fallback。
4. 事件驱动的流式架构
全链路 SSE 流式：Python → Go → React，事件逐层透传。
常见坑
- Go 后端变成纯转发层: Go 不该只是透传请求，应该负责上下文组装、权限、审计
- Python 直接查业务数据库: 打破了层间边界，导致耦合
- 前端直接调 AI Service: 绕过了权限和审计
- 没有统一的事件协议: 每层各自定义事件格式，对接困难
- 过度工程化: MVP 阶段不需要微服务，单体 + 模块化就够了
和其他概念的关系
- vs AI Agent Application: Application 是产品，Stack 是技术选型
- vs Backend For Frontend: BFF 是 Stack 中 Go 层的设计模式
- vs AI Service: AI Service 是 Stack 中的 Agent 引擎层
极简示例
一个最小可用的技术栈：
前端: React + fetch + EventSource
后端: Go (单文件 handler)
AI: Python FastAPI + OpenAI SDK
DB: PostgreSQL + pgvector不需要 Kubernetes、不需要微服务、不需要消息队列。先把单体跑通，再按需拆分。
总结
技术栈分层的核心原则是：每层只做自己擅长的事。前端管渲染，后端管编排和权限，AI Service 管推理和执行，基础设施管存储和计算。层间通过清晰的协议通信，而不是共享数据库。