## モジュール 2: エージェントの作業ディレクトリ永続化を確保する"
```mermaid
---
title: モジュール環境概要
---
flowchart LR
USER["Lab ユーザー"] --> T1["ターミナル 1:
Hermes サンドボックス"]
USER --> T2["ターミナル 2:
VM ホスト"]
T1 --> TD_LAYOUT
T2 --> TD_LAYOUT
%% DIRとその接続: 上下方向に切り替え
subgraph TD_LAYOUT["TiDB Cloud CLIとファイルシステムの活用"]
direction TB
TI1["ti"]
TI1 -->|管理| FS["TiDB Cloud Filesystem
aws-${LAB:REGION_CODE}"]
DIR["ローカル サンドボックス ディレクトリ
aws-${LAB:REGION_CODE}"]
TI1 -->|FUSE マウント| FS
FS -->|FUSE マウント| DIR
end
```
このモジュールでは、演習VM上にプリインストールされたHermes Agentを設定・起動します。`ti` コマンドを使い、VMやエージェント・セッション、サンドボックスのライフサイクルに依存しない永続的なTiDB Cloud Filesystemを作成・マウント・検証し、エージェントのデフォルト作業ディレクトリとします。
### 手順 1: Hermes 標準サンドボックスの設定と Hermes セッション開始
- **[ターミナル 1](ssh://monitor1-ssh#1)** に戻ってください。
- 以下のコマンドでHermesの事前設定済み設定を適用します。設定内容は後で確認します。
```bash
# 事前定義済み設定を適用
cp ~/config.yaml.solution ~/.hermes/config.yaml
```
- 設定を確認してください。詳細は下に記載しています。
```bash
# 設定値の確認
hermes config check
cat ~/.hermes/config.yaml | grep -A17 'terminal:'
```
```output
terminal:
backend: docker
cwd: .
timeout: 720
home_mode: auto
docker_mount_cwd_to_workspace: false
docker_forward_env:
- "TI_FS_TOKEN"
- "TI_REGION_CODE"
- "DATABASE_URL"
docker_run_as_host_user: false
docker_extra_args:
- "--privileged"
- "--device=/dev/fuse"
- "--cap-add=SYS_ADMIN"
- "--security-opt=apparmor=unconfined"
- "--tmpfs=/tmp:rw,nosuid,size=512m,exec"
docker_persist_across_processes: false
```
- Hermes設定のポイント:
- `backend: docker`: Dockerをツールバックエンドとして使い、VM本体ではなくセキュアかつ短命なコンテナ（サンドボックス）でコマンドを実行します。
- `docker_forward_env`: `TI_FS_TOKEN`, `TI_REGION_CODE`, `DATABASE_URL` 環境変数をサンドボックスに転送します。（`DATABASE_URL`は次モジュールで使用）
- `docker_extra_args`: FUSEによるTiDB Cloud Filesystemのマウントに必要なDockerパラメータ（`--privileged`, `--device=/dev/fuse`, `--cap-add=SYS_ADMIN`, `--security-opt=apparmor=unconfined`, 実行可能な `/tmp` tmpfs 等）
- `docker_persist_across_processes: false`: Hermesプロセスごとにコンテナを永続化せず、毎回新しいHermesチャットで新規コンテナを使います。
> [!NOTE]
> 前モジュール同様、環境にTI_FS_TOKENおよびファイルシステムのリージョン情報があれば、TiDB Cloud CLIは追加設定なしでそのファイルシステムをマウントできます。
- Hermesセッションを開始し、Hermesプロンプトに入ります。起動には30秒以上かかる場合があります。
```bash
hermes chat
```
```output
⚕ deepseek.v3.2 │ ctx -- │ [░░░░░░░░░░] -- │ 18s │ ⏲ 0s
──────────────────────────────────────────────────────────────────────────────────
❯
──────────────────────────────────────────────────────────────────────────────────
```
### 手順 2: Hermes Agent に TiDB Cloud CLI を理解させる
- **[ターミナル 1](ssh://monitor1-ssh#1)** 上でエージェントと対話を始めます。
- Hermesに環境変数の出力を指示します。必須の**`TI_`**環境変数（`TI_FS_TOKEN`、`TI_REGION_CODE`）が存在することを確認してください。目的は値の正確さでなく“存在確認”です。
```text
env を実行して
```
```output
╭─ ⚕ Hermes ──────────╮
現在の環境変数を確認します。
.
TI_FS_TOKEN: トークン変数 (セキュリティ上マスク表示)
.
TI_REGION_CODE=aws-${LAB:REGION_CODE}
.
```
- Hermes端末がサンドボックス上で稼働しているか確認します。
```text
ターミナルは短命なサンドボックスコンテナ内で稼働しているか確認してください。
```
```output
╭─ ⚕ Hermes ─────────────────────────────────────────────────╮
確認結果: はい、ターミナルは短命なサンドボックスコンテナ内で稼働しています
証拠:
.
.
.
```
- TiDB Cloud CLIコマンドラインツールの使い方を学ばせます。レスポンスから、エージェントが「統一ストレージ層」の価値を理解しているか観察します。
> [!TIP]
> ここではTiDB Cloud Filesystem専用エージェントスキルは使いません。
```text
https://github.com/tidbcloud/ti-cli を見てください。このツールが提供する機能について教えてください。また、これらの機能を使ってワークフローを改善できますか？
```
```output
╭─ ⚕ Hermes ─────────────────────────────────────────────╮
GitHubリポジトリを確認して、Ti-CLIツールが提供する機能を分析します。
.
.
.
```
- これでHermes AgentはTiDB Cloud Filesystemの利用法や、“統一状態保存層”として使う意義を理解し、その活用方法を検討できるようになります。
### 手順 3: 作業ディレクトリの永続化をエージェント自身に解決させる
- 適切なスキルのインストールをエージェントに指示します。最大3分ほど待つと検証工程も自動で行なわれます。ゆっくり進行を見守ってください。Hermesが承認を求めてきた場合は、「続行」を選択してください。
```text
このスキルを追加してください - https://github.com/pingcap/agent-rules/blob/main/skills/mount-tidb-cloud-fs/SKILL.md
```
```output
╭─ ⚕ Hermes ────────────────────────╮
指定されたURLからスキルを確認し、追加します。
.
.
.
```
- 以下の指示でHermes AgentにTiDB Cloud Filesystemを**持続的かつデフォルト作業ディレクトリ（/workspace）**としてマウントさせ、期待通りか注意深く観察します。
```text
TiDB Cloud Filesystem を FUSE で /workspace ディレクトリに直接マウントし、すべての出力ファイルの保存先として使用してください。最後に、レポートを提出してください。
```
```output
╭─ ⚕ Hermes ───────────────────────────╮
FUSEツールがインストールされているか確認します。
.
.
.
```
> [!NOTE]
> デフォルトでHermesサンドボックスには、FUSE操作に必要な`fusermount`や`ti-cli`ツールは含まれていませんが、エージェントは自動で依存関係を検出しインストールできます。毎回サンドボックス初期化時の再インストールを避けたい場合、これらツールをプリインストールした新規イメージの作成をおすすめします（後述）。
### 手順 4: Hermes Agent で TiDB Cloud Filesystem を本格活用
- Hermes Agentに太陽系ライブラリ的なPythonプログラムの作成を指示します。ファイルの記述が始まったら次に進んでください（完成を待つ必要はありません）。
```text
シンプルなPythonプログラムを作成してください。そのプログラムは太陽系内の任意の惑星について衛星（ムーン）の情報を返すものとしてください。必ず出力ファイルは /workspace ディレクトリ下に保存してください。
```
```output
╭─ ⚕ Hermes ─────────────────────────────────────────────────────╮
プログラムが正常に作成されました。では、このプログラムのテストを実行してみます。
.
.
.
```
### 手順 5: Hermes Agent が TiDB Cloud Filesystem を使っているか検証
- **[ターミナル 2](ssh://monitor1-ssh#2)** に切り替え、新しくターミナルを開きます。
- VMホスト上で以下のコマンドを実行し、Hermes の環境変数（特に `TI_FS_TOKEN`）を取り込み、Hermes サンドボックスの `/workspace` ディレクトリ内で内容に **Solar** を含むファイルを検索します。出力例は環境によって異なります：
```bash
source ~/.hermes/.env
export TI_FS_TOKEN
ti fs search-file-content --pattern Solar
```
> [!IMPORTANT]
> `ti`だけで直接検索可能です。`ti fs search-file-content`は単なるファイル名一致でなく、ファイル内容もセマンティックに検索します。
```output
{
"path": "/",
"results": [
{
"path": "/solar-system-moons/README.md",
"name": "README.md"
},
{
"path": "/solar-system-moons/test_moon_finder.py",
"name": "test_moon_finder.py"
}
]
}
```
### 手順 6: 新たなサンドボックスイメージを作成する
- **[ターミナル 2](ssh://monitor1-ssh#2)** で、TiDB Cloud CLIや依存関係（`ti-cli`, `fusermount`など）を予めインストール済みの **`hermes-sandbox:v1`** というDockerイメージを作成し、サンドボックス再作成ごとの冗長なインストールを避けます。
```bash
docker commit $(docker ps -l -q -f status=running | head -1) hermes-sandbox:v1
```
> [!NOTE]
> この作業は2分ほどかかることがあります（演習用の小型マシンを使用しているため）。気長にお待ちください。
```output
sha256:88212b02b034........a3030400f49b0538579
```
- 次回の新しいセッション起動時に新しいイメージが適用されるよう、Hermes の設定を変更します。
```bash
sed -i '/backend: docker/a\ docker_image: hermes-sandbox:v1' ~/.hermes/config.yaml
hermes config check
```
```output
.
.
.
○ TEAMS_PORT
○ TEAMS_HOST
○ TEAMS_ALLOWED_USERS
○ TEAMS_ALLOW_ALL_USERS
○ TEAMS_HOME_CHANNEL
○ TEAMS_HOME_CHANNEL_NAME
```
### 手順 7: 新しいサンドボックスで TiDB Cloud Filesystem が継承されるかテスト
- **[ターミナル 2](ssh://monitor1-ssh#2)** にて、サンドボックスコンテナが稼働中か以下で確認します（出力は例です）。
```bash
docker ps
```
```output
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
19b7b29802b8 nikolaik/python-nodejs:python3.11-nodejs20 "sleep infinity" 21 minutes ago Up 21 minutes hermes-b401e193
```
- **[ターミナル 1](ssh://monitor1-ssh#1)** に戻り、現在のHermesチャットセッションを終了します。
```text
/quit
```
```output
Resume this session with:
hermes --resume 20260817_000435_239c2f
.
.
.
```
> [!IMPORTANT]
> Hermesセッションを終了すると、その短命サンドボックスコンテナも同時に停止・削除されます。
- **[ターミナル 2](ssh://monitor1-ssh#2)** で、サンドボックスが消滅したことを確認します。
```bash
docker ps
```
```output
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
```
- **[ターミナル 1](ssh://monitor1-ssh#1)** に戻り、新規セッションを開始して新たなサンドボックスにします。
```bash
hermes chat
```
- Hermesに**`/workspace`**ディレクトリの状態を尋ねます。最初は空でも問題ありません（未マウント状態）。
```text
今、/workspace の状態はどうなっていますか？
```
```output
╭─ ⚕ Hermes ──────────────────────────────────────────────╮
さらに詳細を確認するために、ファイルシステムの統計情報も見てみましょう。
.
.
.
```
> [!IMPORTANT]
> `/workspace`へのTiDB Cloud Filesystem自動マウントが実施されなかった場合、次で手動マウントを指示します。
- もしTiDB Cloud Filesystemがまだマウントされていない場合は、下記プロンプトでエージェントに指示し、**データ損失がない**ことを確認します（出力は一例）。
```text
スキルを使ってTiDB Cloud FSをFUSEでマウントしてください。その後、/workspaceディレクトリの構成を表示してください。
```
```output
╭─ ⚕ Hermes ──────────────────────────────────────────────────────────────────────────────────────────────────╮
「sandbox-persistence」というスキルが利用できるはずです。このスキルを確認してTiDB Cloud Filesystemのマウントに使用しましょう。
.
.
.
2. 既存のファイル (前回のセッションから持続):
- hello-world.txt - 20バイト
- data_analysis.csv - 93バイト
- execution.log - 189バイト
- final_report.txt - 3,170バイト
- project_report.md - 1,107バイト
- 月に関するファイル群（moons_*.txt）
- Pythonスクリプト（planet_moons.py, demo_moon_program.py）
- solar_system_moons_summary.txt - 2,332バイト
- usage_examples.txt - 2,571バイト
.
.
.
```
- Hermesチャットを終了してください。
```text
/quit
```
> [!IMPORTANT]
> ここまでで、”2つの独立したエージェントセッションが作業ディレクトリを引き継ぐ”シナリオを模擬しました。実際は、常時自動でTiDB Cloud Filesystemをマウントできるサンドボックス用Dockerイメージの準備が便利です。
次のモジュールへ進んでください。