492 lines
9.2 KiB
Markdown
492 lines
9.2 KiB
Markdown
# Architecture
|
|
|
|
## Overview
|
|
|
|
`Atlas Zero Agent` 采用“单 chatbox 入口 + 多 agent 内部协作”的架构。
|
|
|
|
对外，系统暴露为一个统一的聊天服务；对内，系统通过 `Stella` orchestrator 把请求分发给不同职责的 agent 节点，结合 `LangGraph` 管理状态流转，结合 `LangChain` 管理模型、工具、检索器和提示词。
|
|
|
|
工程目标有三点：
|
|
|
|
- 让 chat 成为统一入口
|
|
- 让 agent runtime 成为核心执行层
|
|
- 让 memory、tools、observability 从一开始就是一等公民
|
|
|
|
## Design Goals
|
|
|
|
- 支持通用聊天与多轮对话
|
|
- 支持工具调用与多步任务执行
|
|
- 支持短期记忆、长期记忆与知识检索
|
|
- 支持流式输出和可恢复执行
|
|
- 支持成本、权限、审计和 trace 管理
|
|
- 支持后续扩展到多租户和插件体系
|
|
|
|
## High-Level Architecture
|
|
|
|
```text
|
|
Client / UI
|
|
-> FastAPI API Layer
|
|
-> Application Services
|
|
-> Stella Orchestrator
|
|
-> LangGraph Runtime
|
|
-> Shaka Guard
|
|
-> Edison Planner
|
|
-> Pythagoras Memory / RAG
|
|
-> Atlas Executor
|
|
-> Lilith Explorer
|
|
-> York Resource Manager
|
|
-> Tool Layer / Memory Layer / Model Layer
|
|
-> Persistence + Observability
|
|
```
|
|
|
|
## Layered Architecture
|
|
|
|
### 1. Interface Layer
|
|
|
|
职责：
|
|
|
|
- 对外暴露 HTTP API
|
|
- 提供同步与流式聊天接口
|
|
- 提供会话查询与管理接口
|
|
- 提供健康检查、调试和管理接口
|
|
|
|
建议技术：
|
|
|
|
- `FastAPI`
|
|
- `Pydantic`
|
|
- `SSE`，后续可选 `WebSocket`
|
|
|
|
建议目录：
|
|
|
|
- `app/api/routes/`
|
|
- `app/api/schemas/`
|
|
|
|
这一层只处理：
|
|
|
|
- 请求解析
|
|
- 参数校验
|
|
- 响应序列化
|
|
- 状态码和错误格式
|
|
|
|
这一层不应该直接写复杂 agent 逻辑。
|
|
|
|
### 2. Application Layer
|
|
|
|
职责：
|
|
|
|
- 接收 API 请求并转成应用层命令
|
|
- 维护 session、user、tenant 上下文
|
|
- 管理鉴权、限流、权限边界
|
|
- 调用 orchestrator 与服务层
|
|
|
|
建议目录：
|
|
|
|
- `app/services/`
|
|
- `app/core/`
|
|
|
|
应用层负责解决“系统怎么接住一个请求”，而不是“模型怎么思考”。
|
|
|
|
### 3. Agent Runtime Layer
|
|
|
|
职责：
|
|
|
|
- 管理多 agent 状态流转
|
|
- 管理节点输入输出和共享状态
|
|
- 管理 checkpoint、中断、恢复和回放
|
|
- 统一 tool call、fallback 和 error routing
|
|
|
|
建议技术：
|
|
|
|
- `LangGraph`
|
|
- `LangChain`
|
|
|
|
建议目录：
|
|
|
|
- `app/runtime/`
|
|
- `app/agents/`
|
|
|
|
核心设计原则：
|
|
|
|
- 每个 agent 有清晰职责
|
|
- 节点之间通过统一 `state` 共享信息
|
|
- 最终只允许少数节点产生对用户可见的最终输出
|
|
- 失败路径必须可观测、可恢复、可降级
|
|
|
|
### 4. Knowledge and Memory Layer
|
|
|
|
职责：
|
|
|
|
- 保存当前会话消息
|
|
- 保存长期用户偏好与任务历史
|
|
- 提供知识库检索与重排
|
|
- 提供对话摘要和记忆压缩
|
|
|
|
建议拆成三类存储：
|
|
|
|
- `Session Store`
|
|
- `Memory Store`
|
|
- `Vector Store`
|
|
|
|
建议目录：
|
|
|
|
- `app/memory/`
|
|
|
|
建议原则：
|
|
|
|
- 短期记忆和长期记忆分开建模
|
|
- 检索上下文和用户消息分开处理
|
|
- 避免把所有历史直接塞进 prompt
|
|
- 优先通过摘要、选择性检索和结构化 memory 控制上下文长度
|
|
|
|
### 5. Tool and Integration Layer
|
|
|
|
职责：
|
|
|
|
- 封装内部工具
|
|
- 封装第三方 API
|
|
- 控制工具权限与调用边界
|
|
- 统一工具描述、输入和输出格式
|
|
|
|
建议目录：
|
|
|
|
- `app/tools/`
|
|
|
|
工具层应该满足：
|
|
|
|
- 可测试
|
|
- 可复用
|
|
- 可审计
|
|
- 可在 runtime 中统一注册
|
|
|
|
后续可预留：
|
|
|
|
- `MCP` 接入
|
|
- browser / search 工具
|
|
- filesystem 工具
|
|
- knowledge connectors
|
|
|
|
### 6. Observability and Governance Layer
|
|
|
|
职责：
|
|
|
|
- 跟踪每次请求的执行链路
|
|
- 记录 tool call、模型调用与成本
|
|
- 记录安全拦截与人工审批事件
|
|
- 输出 metrics、audit log 和 trace
|
|
|
|
建议目录：
|
|
|
|
- `app/observability/`
|
|
|
|
建议技术：
|
|
|
|
- `LangSmith`
|
|
- `OpenTelemetry`
|
|
- `Prometheus`
|
|
- `Grafana`
|
|
|
|
这个层不是后补件，而是 agent 系统能否产品化的关键部分。
|
|
|
|
## Agent Topology
|
|
|
|
### External Identity
|
|
|
|
- `Atlas Zero`: 对外统一产品身份
|
|
|
|
### Internal Roles
|
|
|
|
- `Stella`: orchestrator / router
|
|
- `Shaka`: safety and policy guard
|
|
- `Edison`: planner and workflow builder
|
|
- `Pythagoras`: memory and retrieval manager
|
|
- `Atlas`: executor and tool runner
|
|
- `Lilith`: exploration and fallback agent
|
|
- `York`: resource and budget manager
|
|
|
|
## Minimum Execution Flow
|
|
|
|
第一阶段建议实现如下链路：
|
|
|
|
```text
|
|
User Message
|
|
-> API Layer
|
|
-> Session Service
|
|
-> Stella
|
|
-> Shaka
|
|
-> Edison
|
|
-> Pythagoras
|
|
-> Atlas
|
|
-> Stella Response Composer
|
|
-> Streaming / Final Response
|
|
```
|
|
|
|
各节点职责：
|
|
|
|
- `Stella`: 创建运行上下文，决定是否直接回答还是进入执行链路
|
|
- `Shaka`: 校验风险、权限和策略边界
|
|
- `Edison`: 生成任务计划、决定工具和步骤
|
|
- `Pythagoras`: 读取 session memory、long-term memory 和知识库
|
|
- `Atlas`: 执行工具调用、收集结果、产出 observation
|
|
- `Stella Response Composer`: 汇总结果并形成最终回答
|
|
|
|
## Optional Extended Flow
|
|
|
|
在第二阶段可扩展：
|
|
|
|
```text
|
|
Stella
|
|
-> Shaka
|
|
-> Edison
|
|
-> Pythagoras
|
|
-> Lilith
|
|
-> Atlas
|
|
-> York
|
|
-> Stella
|
|
```
|
|
|
|
扩展后的作用：
|
|
|
|
- `Lilith`: 做多路探索、候选方案试探、失败路径补救
|
|
- `York`: 做模型选择、预算控制、异步任务排队和优先级管理
|
|
|
|
## Runtime State Model
|
|
|
|
建议定义统一运行时状态对象，例如：
|
|
|
|
```text
|
|
RunState
|
|
- run_id
|
|
- session_id
|
|
- user_id
|
|
- tenant_id
|
|
- input_message
|
|
- messages
|
|
- memory_context
|
|
- retrieved_documents
|
|
- plan
|
|
- tool_calls
|
|
- tool_results
|
|
- safety_decision
|
|
- final_response
|
|
- status
|
|
- started_at
|
|
- finished_at
|
|
- usage
|
|
- errors
|
|
```
|
|
|
|
建议原则：
|
|
|
|
- 所有节点都读写同一个共享状态模型
|
|
- 用户可见输出和内部推理中间态要分开存储
|
|
- 工具结果、检索结果、摘要结果要有明确字段
|
|
- 状态对象需要可序列化，方便 checkpoint 和回放
|
|
|
|
## API Design
|
|
|
|
### Core Endpoints
|
|
|
|
- `POST /api/chat`
|
|
- `POST /api/chat/stream`
|
|
- `GET /api/sessions/{session_id}`
|
|
- `GET /api/sessions/{session_id}/messages`
|
|
- `POST /api/sessions/{session_id}/messages`
|
|
- `GET /api/agents`
|
|
- `POST /api/agents/run`
|
|
- `GET /api/runs/{run_id}`
|
|
- `GET /api/health`
|
|
|
|
### Example `POST /api/chat`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"session_id": "sess_123",
|
|
"message": "帮我总结这个项目的架构",
|
|
"agent": "atlas-zero",
|
|
"stream": false,
|
|
"metadata": {
|
|
"user_id": "user_001"
|
|
}
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"run_id": "run_123",
|
|
"session_id": "sess_123",
|
|
"message": {
|
|
"role": "assistant",
|
|
"content": "..."
|
|
},
|
|
"usage": {
|
|
"input_tokens": 0,
|
|
"output_tokens": 0
|
|
},
|
|
"trace_id": "trace_123"
|
|
}
|
|
```
|
|
|
|
### Example `POST /api/chat/stream`
|
|
|
|
建议返回 `SSE` 事件流，事件类型可包括：
|
|
|
|
- `run.started`
|
|
- `message.delta`
|
|
- `tool.started`
|
|
- `tool.finished`
|
|
- `retrieval.finished`
|
|
- `run.completed`
|
|
- `run.failed`
|
|
|
|
这样前端不仅能展示文字流，还能展示 agent 执行过程。
|
|
|
|
## Suggested Project Structure
|
|
|
|
```text
|
|
app/
|
|
api/
|
|
routes/
|
|
chat.py
|
|
sessions.py
|
|
agents.py
|
|
runs.py
|
|
schemas/
|
|
chat.py
|
|
session.py
|
|
run.py
|
|
core/
|
|
config.py
|
|
logging.py
|
|
security.py
|
|
runtime/
|
|
graph.py
|
|
orchestrator.py
|
|
state.py
|
|
checkpoints.py
|
|
agents/
|
|
stella.py
|
|
shaka.py
|
|
edison.py
|
|
pythagoras.py
|
|
atlas.py
|
|
lilith.py
|
|
york.py
|
|
memory/
|
|
session_store.py
|
|
memory_store.py
|
|
vector_store.py
|
|
summarizer.py
|
|
tools/
|
|
registry.py
|
|
search.py
|
|
browser.py
|
|
knowledge.py
|
|
filesystem.py
|
|
services/
|
|
chat_service.py
|
|
session_service.py
|
|
run_service.py
|
|
observability/
|
|
tracing.py
|
|
metrics.py
|
|
audit.py
|
|
main.py
|
|
```
|
|
|
|
## Persistence Design
|
|
|
|
### Recommended Storage
|
|
|
|
- `PostgreSQL`: sessions、messages、runs、audit logs
|
|
- `Redis`: cache、rate limit、ephemeral state、queue metadata
|
|
- `pgvector` or vector DB: embeddings、document chunks、memory retrieval
|
|
|
|
### Minimum Tables
|
|
|
|
- `users`
|
|
- `sessions`
|
|
- `messages`
|
|
- `runs`
|
|
- `tool_calls`
|
|
- `documents`
|
|
- `document_chunks`
|
|
- `memories`
|
|
- `audit_logs`
|
|
|
|
## Security and Governance
|
|
|
|
### Shaka Responsibilities
|
|
|
|
- 敏感请求识别
|
|
- 工具权限控制
|
|
- 高风险动作审批
|
|
- 输出降级和拒答
|
|
|
|
### Governance Rules
|
|
|
|
- 所有工具调用都必须可审计
|
|
- 高风险工具必须支持 allowlist 或人工确认
|
|
- 模型输出不直接代表工具执行成功
|
|
- 用户输入、检索上下文、工具 observation 要分开处理
|
|
|
|
## Observability
|
|
|
|
每个 `run` 至少应采集：
|
|
|
|
- `run_id`
|
|
- `trace_id`
|
|
- `session_id`
|
|
- `agent path`
|
|
- `model usage`
|
|
- `tool usage`
|
|
- `latency`
|
|
- `cost`
|
|
- `failure reason`
|
|
|
|
建议从第一版就支持：
|
|
|
|
- request tracing
|
|
- prompt versioning
|
|
- run replay
|
|
- structured logs
|
|
|
|
## Delivery Plan
|
|
|
|
### Phase 1
|
|
|
|
- `FastAPI` 基础骨架
|
|
- `POST /api/chat` 与 `POST /api/chat/stream`
|
|
- `Stella -> Shaka -> Edison -> Pythagoras -> Atlas` 最小链路
|
|
- session 持久化
|
|
- 基础 RAG
|
|
|
|
### Phase 2
|
|
|
|
- `Lilith` 扩展探索路径
|
|
- `York` 模型路由和预算控制
|
|
- 文件上传、文档切分与知识入库
|
|
- 更完整的 trace 和 metrics
|
|
|
|
### Phase 3
|
|
|
|
- checkpoint 和 resume
|
|
- async job queue
|
|
- approval workflow
|
|
- `MCP` compatibility
|
|
- multi-tenant support
|
|
|
|
## Non-Goals for Early Version
|
|
|
|
第一阶段不建议过早投入：
|
|
|
|
- 复杂可视化工作流编辑器
|
|
- 过多 agent 角色同时上线
|
|
- 过重的插件市场系统
|
|
- 过早拆成微服务
|
|
|
|
建议先把最小闭环跑通，再逐步扩展。
|