> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体运行时

> Zeus Agent 运行时 — 架构、工作空间、会话管理与运行模式

Zeus 的 Agent 模式基于 **DeepAgents** 框架构建，支持自主任务规划、工具调用和执行。运行时负责管理 Agent 的生命周期 — 从工作空间初始化、工具装配、提示词组装，到会话隔离与状态持久化。

## 核心模块

<CardGroup cols={2}>
  <Card title="Bootstrapping" icon="rocket" href="/en/ai-backend/fundamentals/Bootstrapping">
    启动引导 — System Prompt 组装、模式选择、动态上下文注入
  </Card>

  <Card title="HITL" icon="user-check" href="/en/ai-backend/fundamentals/HITL">
    Auto-Run 模式与工具审批机制，确保 Agent 执行敏感操作前获得人类确认
  </Card>

  <Card title="Middleware" icon="layer-group" href="/en/ai-backend/fundamentals/Middleware">
    DeepAgents 中间件管线 — 自动摘要、文件系统、任务管理、提示词缓存等
  </Card>

  <Card title="Models" icon="microchip" href="/en/ai-backend/fundamentals/Models">
    模型配置与管理 — 支持自有 API Key、Zeus 预置模型、200+ 模型 Profile
  </Card>

  <Card title="Context" icon="brain" href="/en/ai-backend/fundamentals/Context">
    Agent 上下文组装、Token 管理与优化策略
  </Card>

  <Card title="Tools" icon="wrench" href="/en/ai-backend/fundamentals/Tools">
    四层工具体系 — Built-in Tools、MCP Tools、OAuth Tools、Connector Tools
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/en/ai-backend/fundamentals/Skills">
    动态指令包 — 代码审查、数据分析、写作助手等可扩展技能
  </Card>

  <Card title="System Prompt" icon="file-lines" href="/en/ai-backend/fundamentals/System-Prompt">
    系统提示词 — CORE、SOUL、TOOLS、WORKFLOW、MEMORY、动态注入
  </Card>

  <Card title="Artifacts" icon="cube" href="/en/ai-backend/fundamentals/Artifacts">
    结构化工具返回格式 — HTML、代码、图表等富内容渲染
  </Card>
</CardGroup>

***

## Workspace

每个用户拥有独立的云端工作空间，由 `CloudDriveBackend` 管理，底层使用 Supabase Storage 持久化，Redis 提供缓存层。

```mermaid theme={null}
graph TD
    subgraph Supabase["Supabase Storage"]
        subgraph UserDir["users/{user_id}/"]
            workspace["workspace/<br/>Agent 工作产出"]
            memory_dir["memory/<br/>长期记忆文件"]
        end
    end

    subgraph Backend["CloudDriveBackend"]
        ls["ls_info()"]
        read["read_file()"]
        write["write_file()"]
        edit["edit_file()"]
        grep["grep()"]
        glob["glob()"]
    end

    subgraph Cache["Redis Cache"]
        ws_cache["workspace 缓存<br/>TTL: 5min"]
        mem_cache["memory 缓存<br/>TTL: 10min"]
    end

    Backend -->|"读取"| Cache
    Cache -->|"miss"| Supabase
    Backend -->|"写入 (invalidate cache)"| Supabase
```

| 路径                                          | 说明                 |
| ------------------------------------------- | ------------------ |
| `users/{user_id}/workspace/`                | Agent 的工作目录，存放产出文件 |
| `users/{user_id}/workspace/projects/`       | 项目文件               |
| `users/{user_id}/workspace/sandbox-output/` | 沙盒执行结果             |
| `users/{user_id}/workspace/uploads/`        | 用户上传文件             |
| `users/{user_id}/memory/`                   | 长期记忆文件             |

<Card title="文件系统详细设计" icon="folder-open" href="/en/ai-backend/file-system/overview">
  了解 CloudDriveBackend、Checkpoint 等存储架构的完整设计
</Card>

***

## Sessions

每个对话创建一个独立 Session，提供状态隔离：

```mermaid theme={null}
graph LR
    session_id["session_id<br/>(前端生成 or 自动生成)"]
    thread_id["thread_id<br/>(Checkpointer 隔离键)"]
    context_cache["context_cache<br/>(工具 + 提示词缓存)"]

    session_id -->|"1:1 映射"| thread_id
    session_id -->|"缓存键"| context_cache
```

* **Session ID**：格式为 `session_{hex12}`，由前端提供或自动生成
* **Thread ID**：与 Session ID 一致，用于 Checkpointer 状态隔离
* **Context Cache**：按 session\_id 存储工具列表、系统提示词、中断配置，供 HITL 恢复时复用

### Checkpointer

状态持久化通过 LangGraph 的 Checkpointer 机制实现：

| 环境    | 实现              | 说明                     |
| ----- | --------------- | ---------------------- |
| 生产    | `PostgresSaver` | PostgreSQL 持久化，支持跨进程恢复 |
| 开发/回退 | `MemorySaver`   | 内存存储，进程重启后丢失           |

Checkpointer 自动在每次 Agent 调用后保存完整状态（消息、工具调用、Agent 内部状态），使得 HITL 中断和页面刷新后的恢复成为可能。

<Card title="Checkpoint 存储方案" icon="database" href="/en/ai-backend/file-system/Checkpoint">
  了解 PostgresSaver 的详细配置与 HITL 恢复流程
</Card>

***

## Modes

Zeus 支持三种交互模式，每种模式限定了 Agent 的工具集和行为边界：

```mermaid theme={null}
graph TD
    subgraph AgentMode["Agent Mode"]
        direction TB
        agent_desc["完整工具访问<br/>可执行、修改、创建<br/>支持 HITL 审批"]
    end

    subgraph AskMode["Ask Mode"]
        direction TB
        ask_desc["只读工具<br/>分析、问答、探索<br/>引导切换到 Agent 模式"]
    end

    subgraph PlanMode["Plan Mode"]
        direction TB
        plan_desc["只读（不执行）<br/>研究、设计、规划<br/>输出结构化方案"]
    end

    AskMode -->|"需要执行"| AgentMode
    PlanMode -->|"方案确认"| AgentMode
    AgentMode -->|"需要规划"| PlanMode
```

### 模式对比

| 特性      | Agent     | Ask     | Plan      |
| ------- | --------- | ------- | --------- |
| 文件读取    | 可         | 可       | 可         |
| 文件写入    | 可         | 不可      | 不可        |
| 沙盒执行    | 可         | 不可      | 不可        |
| 记忆读取    | 可         | 不可      | 可         |
| 记忆写入    | 可         | 不可      | 不可        |
| HITL 审批 | 可         | 不可      | 不可        |
| 工具调用    | 全部        | 只读子集    | 只读子集      |
| 典型场景    | 编码、部署、自动化 | 代码解读、问答 | 架构设计、方案对比 |

模式在 `invoke()` 入口处立即生效，通过禁用标志和工具过滤实现。Ask 模式禁用沙盒、记忆写入和 HITL；Plan 模式禁用沙盒和 HITL，但保留记忆读取以获取上下文。