atlas-zero-agent/docs/architecture.md

Architecture

Overview

Atlas Zero Agent 采用“单 chatbox 入口 + 多 agent 内部协作”的架构。

对外，系统暴露为一个统一的聊天服务；对内，系统通过 Stella orchestrator 把请求分发给不同职责的 agent 节点，结合 LangGraph 管理状态流转，结合 LangChain 管理模型、工具、检索器和提示词。

工程目标有三点：

• 让 chat 成为统一入口
• 让 agent runtime 成为核心执行层
• 让 memory、tools、observability 从一开始就是一等公民

Design Goals

• 支持通用聊天与多轮对话
• 支持工具调用与多步任务执行
• 支持短期记忆、长期记忆与知识检索
• 支持流式输出和可恢复执行
• 支持成本、权限、审计和 trace 管理
• 支持后续扩展到多租户和插件体系

High-Level Architecture

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

第一阶段建议实现如下链路：

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

在第二阶段可扩展：

Stella
  -> Shaka
  -> Edison
  -> Pythagoras
  -> Lilith
  -> Atlas
  -> York
  -> Stella

扩展后的作用：

• Lilith: 做多路探索、候选方案试探、失败路径补救
• York: 做模型选择、预算控制、异步任务排队和优先级管理

Runtime State Model

建议定义统一运行时状态对象，例如：

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:

{
  "session_id": "sess_123",
  "message": "帮我总结这个项目的架构",
  "agent": "atlas-zero",
  "stream": false,
  "metadata": {
    "user_id": "user_001"
  }
}

Response:

{
  "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

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 角色同时上线
• 过重的插件市场系统
• 过早拆成微服务

建议先把最小闭环跑通，再逐步扩展。