> ## 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.

# Agent Runtime

> Zeus Agent Runtime — Architecture, Workspace, Session Management & Operating Modes

Zeus's Agent mode is built on the **DeepAgents** framework, supporting autonomous task planning, tool invocation, and execution. The runtime manages the Agent's lifecycle — from workspace initialization, tool assembly, and prompt construction to session isolation and state persistence.

## Core Modules

<CardGroup cols={2}>
  <Card title="Bootstrapping" icon="rocket" href="/en/documentation/fundamentals/bootstrapping">
    Startup bootstrapping — System Prompt assembly, mode selection, dynamic context injection
  </Card>

  <Card title="HITL" icon="user-check" href="/en/documentation/core-capabilities/hitl">
    Auto-Run modes and tool approval mechanism, ensuring human confirmation before sensitive operations
  </Card>

  <Card title="Middleware" icon="layer-group" href="/en/documentation/core-capabilities/middleware">
    DeepAgents middleware pipeline — auto-summarization, filesystem, task management, prompt caching
  </Card>

  <Card title="Models" icon="microchip" href="/en/documentation/core-capabilities/models">
    Model configuration & management — custom API Keys, Zeus preset models, 200+ model profiles
  </Card>

  <Card title="Context" icon="brain" href="/en/documentation/core-capabilities/context">
    Agent context assembly, Token management & optimization strategies
  </Card>

  <Card title="Tools" icon="wrench" href="/en/documentation/core-capabilities/tools">
    Four-layer tool system — Built-in Tools, MCP Tools, OAuth Tools, Connector Tools
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/en/documentation/core-capabilities/skills">
    Dynamic instruction packages — code review, data analysis, writing assistant, and other extensible skills
  </Card>

  <Card title="System Prompt" icon="file-lines" href="/en/documentation/core-capabilities/system-prompt">
    System prompt — CORE, SOUL, TOOLS, WORKFLOW, MEMORY, dynamic injection
  </Card>

  <Card title="Artifacts" icon="cube" href="/en/documentation/core-capabilities/artifacts">
    Structured tool return format — HTML, code, charts, and other rich content rendering
  </Card>
</CardGroup>

***

## Workspace

Each user has an independent cloud workspace managed by `CloudDriveBackend`, backed by Supabase Storage for persistence and Redis for caching.

```mermaid theme={null}
graph TD
    subgraph Supabase["Supabase Storage"]
        subgraph UserDir["users/{user_id}/"]
            workspace["workspace/<br/>Agent work output"]
            memory_dir["memory/<br/>Long-term memory files"]
        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 cache<br/>TTL: 5min"]
        mem_cache["memory cache<br/>TTL: 10min"]
    end

    Backend -->|"Read"| Cache
    Cache -->|"miss"| Supabase
    Backend -->|"Write (invalidate cache)"| Supabase
```

| Path                                        | Description                                |
| ------------------------------------------- | ------------------------------------------ |
| `users/{user_id}/workspace/`                | Agent's working directory for output files |
| `users/{user_id}/workspace/projects/`       | Project files                              |
| `users/{user_id}/workspace/sandbox-output/` | Sandbox execution results                  |
| `users/{user_id}/workspace/uploads/`        | User-uploaded files                        |
| `users/{user_id}/memory/`                   | Long-term memory files                     |

<Card title="File System Detailed Design" icon="folder-open" href="/en/documentation/core-capabilities/file-system/overview">
  Learn about the complete design of CloudDriveBackend, Checkpoint, and other storage architecture
</Card>

***

## Sessions

Each conversation creates an independent Session for state isolation:

```mermaid theme={null}
graph LR
    session_id["session_id<br/>(frontend-generated or auto-generated)"]
    thread_id["thread_id<br/>(Checkpointer isolation key)"]
    context_cache["context_cache<br/>(tool + prompt cache)"]

    session_id -->|"1:1 mapping"| thread_id
    session_id -->|"cache key"| context_cache
```

* **Session ID**: Format is `session_{hex12}`, provided by the frontend or auto-generated
* **Thread ID**: Same as Session ID, used for Checkpointer state isolation
* **Context Cache**: Stores tool list, system prompt, and interrupt configuration per session\_id, reused during HITL recovery

### Checkpointer

State persistence is implemented via LangGraph's Checkpointer mechanism:

| Environment          | Implementation  | Description                                             |
| -------------------- | --------------- | ------------------------------------------------------- |
| Production           | `PostgresSaver` | PostgreSQL persistence, supports cross-process recovery |
| Development/Fallback | `MemorySaver`   | In-memory storage, lost on process restart              |

The Checkpointer automatically saves the complete state after each Agent call (messages, tool calls, Agent internal state), enabling recovery after HITL interrupts and page refreshes.

<Card title="Checkpoint Storage" icon="database" href="/en/documentation/core-capabilities/file-system/checkpoint">
  Learn about PostgresSaver detailed configuration and HITL recovery flow
</Card>

***

## Modes

Zeus supports three interaction modes, each constraining the Agent's tool set and behavioral boundaries:

```mermaid theme={null}
graph TD
    subgraph AgentMode["Agent Mode"]
        direction TB
        agent_desc["Full tool access<br/>Can execute, modify, create<br/>Supports HITL approval"]
    end

    subgraph AskMode["Ask Mode"]
        direction TB
        ask_desc["Read-only tools<br/>Analysis, Q&A, exploration<br/>Guides switch to Agent mode"]
    end

    subgraph PlanMode["Plan Mode"]
        direction TB
        plan_desc["Read-only (no execution)<br/>Research, design, planning<br/>Outputs structured plans"]
    end

    AskMode -->|"Needs execution"| AgentMode
    PlanMode -->|"Plan confirmed"| AgentMode
    AgentMode -->|"Needs planning"| PlanMode
```

### Mode Comparison

| Feature           | Agent                          | Ask                    | Plan                                 |
| ----------------- | ------------------------------ | ---------------------- | ------------------------------------ |
| File read         | Yes                            | Yes                    | Yes                                  |
| File write        | Yes                            | No                     | No                                   |
| Sandbox execution | Yes                            | No                     | No                                   |
| Memory read       | Yes                            | No                     | Yes                                  |
| Memory write      | Yes                            | No                     | No                                   |
| HITL approval     | Yes                            | No                     | No                                   |
| Tool calls        | All                            | Read-only subset       | Read-only subset                     |
| Typical scenarios | Coding, deployment, automation | Code explanation, Q\&A | Architecture design, plan comparison |

Modes take effect immediately at the `invoke()` entry point, implemented through disable flags and tool filtering. Ask mode disables sandbox, memory writes, and HITL; Plan mode disables sandbox and HITL but retains memory read access for context.