02-技术架构深度解析

2.1 整体架构概览

Suna采用微服务风格的分层架构，由四个核心组件构成，通过明确的接口边界实现关注点分离。这种架构设计兼顾了开发效率、运行时隔离和水平扩展能力。

graph TB
    subgraph "Frontend Layer"
        FE[Next.js Dashboard<br/>React + TypeScript]
    end
    
    subgraph "API Layer"
        API[FastAPI Backend<br/>Python + LiteLLM]
    end
    
    subgraph "Runtime Layer"
        AR[Agent Runtime<br/>Docker Containers]
    end
    
    subgraph "Data Layer"
        DB[(Supabase<br/>PostgreSQL + Storage)]
    end
    
    FE <-->|REST/WebSocket| API
    API <-->|gRPC/HTTP| AR
    API <-->|SQL/Realtime| DB
    AR -->|State Persist| DB

2.1.1 架构设计哲学

Suna的架构设计体现了以下核心原则：

1. 关注点分离：前端、API、运行时、数据层各司其职
2. 运行时隔离：每个Agent运行在独立的Docker容器中，确保安全
3. 可扩展性：各组件可独立水平扩展
4. 开发效率：采用主流技术栈，降低学习成本

2.2 核心组件详解

2.2.1 Backend API（Python/FastAPI）

技术栈：Python 3.11+, FastAPI, LiteLLM, Pydantic

Backend API是Suna平台的核心大脑，负责：

Agent编排与生命周期管理

# 概念性代码展示Agent编排核心逻辑
class AgentOrchestrator:
    async def execute_task(self, agent_id: str, task: Task) -> TaskResult:
        # 1. 加载Agent配置
        agent_config = await self.get_agent_config(agent_id)
        
        # 2. 创建执行线程
        thread = await self.create_thread(agent_id, task)
        
        # 3. 调用LLM进行规划
        plan = await self.llm.plan(task, agent_config.tools)
        
        # 4. 执行计划步骤
        for step in plan.steps:
            result = await self.execute_step(step, thread)
            thread.add_observation(result)
            
        # 5. 返回结果
        return TaskResult(thread=thread, output=thread.get_final_output())

LLM集成（LiteLLM）

Suna通过LiteLLM实现对多厂商LLM的统一调用：

设计亮点：通过LiteLLM的抽象层，Suna可以在不修改业务代码的情况下切换LLM提供商，便于成本优化和故障转移。

工具系统（Tool System）

工具系统是Suna实现Agent行动能力的关键：

# 工具注册与调用示例
class ToolRegistry:
    def register_tool(self, tool: BaseTool):
        """注册工具到全局注册表"""
        self._tools[tool.name] = tool
    
    async def execute(self, tool_name: str, params: dict) -> ToolResult:
        """执行指定工具"""
        tool = self._tools.get(tool_name)
        if not tool:
            raise ToolNotFoundError(tool_name)
        return await tool.execute(params)

内置工具类别：

2.2.2 Frontend Dashboard（Next.js/React）

技术栈：Next.js 14, React 18, TypeScript, Tailwind CSS, Shadcn UI

Frontend提供可视化的Agent管理和交互界面：

核心功能模块

graph LR
    subgraph "Dashboard"
        A[Agent管理] --> B[可视化构建器]
        A --> C[聊天界面]
        B --> D[工具配置]
        C --> E[实时监控]
    end

1. Agent管理界面

   • Agent列表和状态查看
   • 配置编辑和版本管理
   • 部署控制（启动/停止/重启）

2. 可视化构建器

   • 拖拽式工具配置
   • 工作流编排界面
   • 提示词模板编辑器

3. 聊天界面

   • 类ChatGPT的对话体验
   • 实时消息流（WebSocket）
   • 执行过程可视化（思考链、工具调用）

技术亮点

• Server Components：大量使用Next.js Server Components减少客户端JS体积
• 实时通信：WebSocket实现Agent执行状态的实时推送
• 响应式设计：支持桌面和移动设备

2.2.3 Agent Runtime（Docker）

技术栈：Docker, Python, Playwright, 沙箱环境

Agent Runtime是Suna架构中最具特色的部分——每个Agent实例运行在独立的Docker容器中。

运行时架构

graph TB
    subgraph "Host Machine"
        subgraph "Agent Container A"
            AA[Agent Process]
            AB[Browser<br/>Playwright]
            AC[File System<br/>Volume Mount]
        end
        
        subgraph "Agent Container B"
            BA[Agent Process]
            BB[Browser<br/>Playwright]
            BC[File System<br/>Volume Mount]
        end
        
        D[Docker Daemon]
    end
    
    D --> AA
    D --> BA

安全隔离机制

设计优势：

1. 安全性：即使Agent执行恶意代码，影响范围仅限于容器内部
2. 稳定性：单个Agent的崩溃不会影响平台其他部分
3. 可扩展性：容器可快速启动和销毁，支持动态扩缩容

2.2.4 Database & Storage（Supabase）

技术栈：PostgreSQL, Supabase Auth, Supabase Storage, Realtime

Supabase为Suna提供一站式数据层：

数据模型概览

-- 核心数据表（概念展示）
-- Agent定义表
CREATE TABLE agents (
    id UUID PRIMARY KEY,
    name VARCHAR(255),
    config JSONB,          -- Agent配置（工具、提示词等）
    owner_id UUID,
    created_at TIMESTAMP
);

-- 对话线程表
CREATE TABLE threads (
    id UUID PRIMARY KEY,
    agent_id UUID,
    status VARCHAR(50),    -- running, completed, error
    context JSONB,         -- 对话上下文
    created_at TIMESTAMP
);

-- 执行日志表
CREATE TABLE executions (
    id UUID PRIMARY KEY,
    thread_id UUID,
    tool_name VARCHAR(255),
    input JSONB,
    output JSONB,
    duration_ms INTEGER,
    created_at TIMESTAMP
);

Supabase特性应用

2.3 技术选型分析

2.3.1 为什么选择FastAPI而非Node.js？

Suna前端使用Next.js（Node.js生态），但Backend选择Python/FastAPI，原因包括：

2.3.2 为什么选择Supabase而非自建数据库？

2.3.3 为什么选择Docker而非进程隔离？

2.4 数据流与执行流程

2.4.1 Agent执行完整流程

sequenceDiagram
    participant U as 用户
    participant F as Frontend
    participant A as FastAPI
    participant D as Docker Runtime
    participant L as LLM Provider
    participant B as Browser/Tool
    participant DB as Supabase

    U->>F: 发送任务
    F->>A: POST /api/execute
    A->>DB: 创建线程记录
    A->>D: 启动Agent容器
    D->>A: 容器就绪
    
    loop 任务执行
        A->>L: 请求LLM决策
        L->>A: 返回下一步动作
        
        alt 需要工具执行
            A->>D: 发送工具调用指令
            D->>B: 执行浏览器/系统操作
            B->>D: 返回执行结果
            D->>A: 返回观察结果
        end
        
        A->>DB: 保存执行日志
        A->>F: WebSocket推送状态
    end
    
    A->>DB: 更新线程状态
    A->>F: 返回最终结果
    F->>U: 展示结果

2.4.2 关键设计模式

模式1：ReAct循环（Reasoning + Acting）

Suna的Agent核心采用ReAct模式：

Thought（思考）→ Action（行动）→ Observation（观察）→ ... → Answer（回答）

这种设计使Agent能够：

• 显式展示推理过程（可解释性）
• 根据观察结果动态调整策略（适应性）
• 错误时自我纠正（鲁棒性）

模式2：工具调用模式（Function Calling）

# LLM决策后返回结构化工具调用
{
    "thought": "我需要搜索最新信息",
    "action": {
        "tool": "web_search",
        "params": {"query": "2026年AI Agent趋势"}
    }
}

优势：

• 结构化输出便于程序解析
• 与主流LLM的function calling能力对齐
• 支持工具调用的串行和并行执行

模式3：事件溯源（Event Sourcing）

Suna的线程（Thread）采用事件溯源模式存储执行历史：

interface ThreadEvent {
    id: string;
    type: 'user_message' | 'assistant_message' | 'tool_call' | 'tool_result';
    payload: unknown;
    timestamp: Date;
}

优势：

• 完整的执行历史可追溯
• 支持从中断点恢复执行
• 便于调试和审计

2.5 性能与扩展性考量

2.5.1 水平扩展策略

graph TB
    subgraph "Load Balancer"
        LB[Nginx/Traefik]
    end
    
    subgraph "API Cluster"
        API1[FastAPI Instance 1]
        API2[FastAPI Instance 2]
        API3[FastAPI Instance N]
    end
    
    subgraph "Runtime Cluster"
        RT1[Docker Host 1]
        RT2[Docker Host 2]
        RT3[Docker Host N]
    end
    
    LB --> API1
    LB --> API2
    LB --> API3
    API1 --> RT1
    API2 --> RT2
    API3 --> RT3

2.5.2 性能瓶颈分析

2.6 参考资料

• Suna Architecture Diagram - 官方架构图
• FastAPI Documentation - FastAPI官方文档
• Supabase Documentation - Supabase官方文档
• LiteLLM Documentation - LiteLLM统一LLM调用文档