celltype-agent 完整教學指南

一句話定位：celltype-agent（CLI：ct）是藥物探索版的 AI coding agent——輸入自然語言問題，AI 自動規劃並呼叫 190+ 計算生物學工具，輸出完整研究報告。

1. 專案定位與核心概念

什麼是 celltype-agent？

celltype-agent 是 CellType Inc. 開源的藥物探索自主代理。它將 Claude Agent SDK 的代理迴圈與 190+ 計算生物學工具組合，讓研究人員只需輸入自然語言問題，就能自動執行多步驟的藥物研究工作流：

1使用者問題
2    │
3    ▼
4Claude（規劃 → 呼叫工具 → 自我修正 → 合成）
5    │
6    ▼
7研究報告（Markdown + HTML）

核心特點

190+ 藥物探索工具：涵蓋標靶優先化、化合物分析、劑量-反應建模、通路富集、安全性評估等
Claude Agent SDK 驅動：以 in-process MCP server 方式暴露所有工具，Claude 在單一 session 最多執行 30 輪工具呼叫
託管資料管線：一行指令下載 DepMap、PRISM、L1000、蛋白質體學資料集
30+ 資料庫 API：PubMed、ChEMBL、UniProt、Open Targets、ClinicalTrials.gov 等
研究導向 UX：互動終端機、@mentions、session 繼續、追蹤記錄、HTML 報告、Jupyter notebook 匯出
MIT 開源：免費使用，可自行部署

適合對象

藥物探索研究人員（需要快速執行標靶/化合物分析）
計算生物學家（需要串接多種生物資訊工具）
製藥 / 生技公司（需要可重複、可稽核的 AI 輔助研究流程）

2. 安裝指南

系統需求

Python 3.10+（必要）
ANTHROPIC_API_KEY（必要，用於 Claude）
可選：RDKit、scanpy、torch（各有對應工具）
可選：Docker（用於本地 GPU 工具）

快速安裝（推薦）

1curl -fsSL https://raw.githubusercontent.com/celltype/celltype-agent/main/install.sh | bash

安裝腳本會自動偵測 Python 版本、優先使用 uv / pipx / pip 安裝，並啟動設定精靈。

手動安裝

1# pipx（隔離環境，推薦）
2pipx install celltype-cli
3
4# pip（基礎版）
5pip install celltype-cli
6
7# 安裝全部選用科學套件（RDKit、scanpy、torch 等）
8pip install "celltype-cli[all]"

開發環境安裝

1git clone https://github.com/celltype/celltype-agent.git
2cd celltype-agent
3pip install -e ".[dev]"
4ct setup
5pytest tests/

認證設定

1# 互動式設定精靈（推薦）
2ct setup
3
4# 直接設定環境變數
5export ANTHROPIC_API_KEY="sk-ant-..."
6
7# CI / 非互動模式
8ct setup --api-key sk-ant-api03-...

驗證安裝

1ct doctor      # 執行完整環境診斷
2ct --version   # 確認版本（目前 0.2.1）

3. 核心架構解析

目錄結構

 1src/ct/
 2├── cli.py              # CLI 入口（~2153行，所有指令定義）
 3├── agent/
 4│   ├── runner.py       # AgentRunner：代理主迴圈（~690行）
 5│   ├── mcp_server.py   # in-process MCP server（工具暴露層）
 6│   ├── system_prompt.py # Claude system prompt
 7│   ├── session.py      # Session 持久化
 8│   ├── trajectory.py   # 工具呼叫追蹤
 9│   ├── sandbox.py      # Python 沙盒執行環境
10│   └── orchestrator.py # 多代理協調
11├── tools/              # 190+ 工具（registry 模式）
12│   ├── structure.py    # 蛋白質結構分析
13│   ├── chemistry.py    # 化學分析
14│   ├── expression.py   # 基因表現分析
15│   ├── viability.py    # 細胞存活分析
16│   ├── literature.py   # 文獻搜尋
17│   ├── shell.py        # Shell 執行工具
18│   ├── alphafold2/     # AlphaFold2 整合
19│   ├── esm2/           # ESM2 蛋白質嵌入
20│   ├── boltz2/         # Boltz2 結構預測
21│   └── ...（17 個工具目錄）
22├── data/
23│   ├── catalog.py      # 資料集目錄
24│   ├── downloader.py   # 資料集下載器
25│   └── loaders.py      # 資料載入器（DepMap / PRISM / L1000）
26├── models/
27│   └── llm.py          # LLM 抽象層（Anthropic / OpenAI / 本地 / GlueML）
28├── cloud/
29│   ├── router.py       # ComputeRouter（本地 vs 雲端路由）
30│   └── client.py       # Modal 雲端 GPU 客戶端
31├── kb/                 # 知識庫
32│   ├── ingest.py       # 知識攝取
33│   └── reasoning.py    # 知識推理
34└── ui/
35    └── terminal.py     # 互動終端機（Rich + prompt-toolkit）

代理執行模型

1# 代理核心：單一 session 最多 30 輪工具呼叫
2AgentRunner
3  ├── 接收自然語言問題
4  ├── Claude 規劃（system_prompt 含工具描述）
5  ├── 呼叫工具（via in-process MCP server）
6  ├── 自我修正（claude-agent-sdk 處理工具結果）
7  └── 合成最終報告（Markdown + HTML）

工具 Registry 模式

所有工具都遵循統一的 registry 模式，讓 Claude 能夠一致地呼叫：

 1@registry.register(
 2    name="category.tool_name",
 3    description="工具說明（Claude 看到的描述）",
 4    category="category",
 5    parameters={"param": "參數說明"},
 6    requires_data=["depmap"],  # 選用：宣告需要哪些資料集
 7)
 8def tool_name(param: str = "default", **kwargs) -> dict:
 9    # 重要：data loader 延遲 import（避免不必要的依賴）
10    from ct.data.loaders import load_depmap
11    ...
12    return {
13        "summary": "人類可讀的結果摘要",  # 必要欄位
14        # ... 其他資料欄位
15    }

規則：

name 前綴必須符合 category
永遠接受 **kwargs
永遠回傳含 "summary" 鍵的 dict
data loader 在函式內部延遲 import

計算路由（本地 vs 雲端）

1ComputeRouter
2├── 本地工具 → LocalRunner（Docker）
3│   └── structure.py、esm2、esmfold（有 GPU 時）
4└── 雲端工具 → CloudClient（Modal）
5    └── AlphaFold2-multimer、boltz2、rfdiffusion 等
6        （計算密集型，需要雲端 GPU）

4. Helper Scripts 詳細用法

CLI 主要指令

 1# 基本使用
 2ct                              # 啟動互動模式
 3ct "問題"                       # 單次查詢
 4ct --model claude-opus-4-6      # 指定 LLM 模型
 5ct --continue                   # 繼續上一個 session
 6
 7# 工具管理
 8ct tool list                    # 列出所有 190+ 工具
 9ct tool pull alphafold2         # 下載工具容器映像
10
11# 資料管理
12ct data pull depmap             # 下載 DepMap 資料集
13ct data pull prism              # 下載 PRISM 細胞存活資料
14ct data pull msigdb             # 下載 gene set 資料
15ct data pull alphafold          # 下載 AlphaFold 結構（按需）
16ct config set data.depmap /path/to/data/  # 指向現有資料
17
18# Session 管理
19ct sessions                     # 列出歷史 session
20ct resume <session_id>          # 恢復指定 session
21
22# 報告
23ct report list                  # 列出所有報告
24ct report publish               # 最新報告 .md → HTML
25ct report show                  # 瀏覽器開啟報告
26
27# 設定
28ct config set key value         # 設定配置項目
29ct setup                        # 重新執行設定精靈
30ct doctor                       # 環境診斷
31
32# 版本
33ct --version

互動模式指令

在 ct 互動模式中，輸入以 / 開頭的指令：

1/help                    # 完整指令參考 + 使用範例
2/tools                   # 列出所有工具及其狀態
3/agents N <query>        # 執行 N 個平行研究代理
4/case-study <id>         # 策劃的多代理案例研究
5/sessions, /resume       # Session 生命週期管理
6/copy, /export           # 儲存 / 分享輸出結果
7/usage                   # Token 與成本追蹤

資料集腳本

1# scripts/prepare_datasets.py：準備分析用資料集
2python scripts/prepare_datasets.py
3
4# scripts/prepare_l1000.py：處理 L1000 轉錄體資料
5python scripts/prepare_l1000.py

5. 應用場景

場景一：標靶優先化（分子膠水研究）

1$ ct "I have a CRBN molecular glue. Proteomics shows it degrades
2      IKZF1, GSPT1, and CK1α. Which target should I prioritize?"

代理會自動：1. 查 DepMap 各標靶的細胞必需性；2. 比較 ChEMBL 化合物活性；3. 查文獻（PubMed）；4. 合成標靶優先化報告

場景二：聯合用藥策略

1$ ct "My lead compound is immune-cold. What combination strategy should I use?"

代理會：評估腫瘤免疫微環境 → 查 PRISM 資料 → 搜尋聯合用藥文獻 → 提出有資料支撐的聯合策略

場景三：抗藥性生物標記

1$ ct "Build a resistance biomarker panel for my lead compound"

代理會：分析 DepMap 突變敏感性 → 整合 L1000 表現簽章 → 建立抗藥性生物標記面板

場景四：蛋白質結構預測

1ct tool pull esmfold    # 先準備工具容器
2ct "Predict the structure of this sequence: MKTIIALSYIFCLVFA..."

場景五：多代理平行研究

1/agents 3 "Evaluate STAT3 as a degradation target for diffuse large B-cell lymphoma"

3 個代理並行：一個做標靶評估、一個做安全性分析、一個做文獻整理

場景六：使用本地資料

1ct config set data.depmap /path/to/DepMap_24Q2/
2ct "Which cancer cell lines show the highest IKZF1 dependency?"

6. 資安掃描報告

掃描時間：2026-05-18 | 掃描工具：grep 靜態分析 | 掃描範圍：src/ scripts/ install.sh

整體評估：🟡 中等風險（需注意幾個設計選擇）

🟢 低風險

API Key 管理良好

API key 透過環境變數讀取（ANTHROPIC_API_KEY、OPENAI_API_KEY、CLUE_API_KEY）
無 hardcode secret
ct setup 輸入時有遮罩顯示（masked feedback）

資料載入器隔離

data loader 使用延遲 import，避免啟動時觸發不必要的資料存取

🟡 中等風險

1. subprocess 使用（tools/structure.py）

1# 用於執行 AlphaFold2、ESMFold、MMseqs2 等本地科學工具
2result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)

風險：命令路徑來自固定腳本，非直接使用者輸入，風險有限。但若容器映像被篡改，仍有執行惡意程式的潛力。

建議：確認 ct tool pull 下載的容器映像來源，驗證 SHA-256

2. Shell Execution Tool（tools/shell.py）

shell.py 提供讓 Claude 執行 shell 指令的工具，有黑名單保護：

1# 黑名單：sudo、rm -rf /、fork bomb 等 26+ 危險指令
2_BLOCKED_PATTERNS = ("sudo ", "rm -rf /", ":(){ :|:& };:", ...)
3_BLOCKED_BINARIES = {"sudo", "su", "rm", "rmdir", ...}

風險：黑名單可能被繞過（如路徑替代、別名）。白名單方法更安全。

建議：評估是否需要此工具；若需要，考慮加入審計日誌

3. Python 沙盒（agent/sandbox.py）

1# 用 exec() 執行 Claude 生成的 Python 程式碼
2# 透過 _BLOCKED_MODULES 阻止危險模組：subprocess、socket、http.server...

風險：黑名單式攔截（非容器隔離），進階 Python 技巧可能繞過。

建議：僅在受信任環境使用；敏感環境考慮 gVisor / nsjail 容器隔離

4. Curl-pipe 安裝模式

1curl -fsSL https://raw.githubusercontent.com/... | bash

風險：若 GitHub 被入侵或網路遭中間人攻擊，可執行任意程式碼。安裝腳本本身有 set -euo pipefail，較安全。

建議：生產環境建議使用 pipx install celltype-cli（PyPI 有 PGP 簽名驗證）

5. Version Check（update_checker.py）

1# urllib.request.urlopen() 請求 PyPI API
2with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT) as resp:

風險：無 certificate pinning；若 DNS 被污染可能連到錯誤端點。風險較低（僅讀取版本號）。

🔴 高風險

無發現高風險問題。

7. FAQ

Q: 沒有本地資料集可以用嗎？

A: 可以。ct 有 30+ 資料庫 API 的整合（PubMed、ChEMBL、UniProt 等），即使沒有本地 DepMap / PRISM 資料仍能運作。標靶/存活相關工具會自動降級到 API 模式。

Q: 支援 OpenAI 的模型嗎？

A: 支援。models/llm.py 有 Anthropic / OpenAI / 本地 VLLM / GlueML 四個後端。設定 OPENAI_API_KEY 後可切換。

Q: 支援 Anthropic Azure Foundry（學術機構用）嗎？

A: 已支援（Issue #2 已關閉）。設定 ANTHROPIC_FOUNDRY_API_KEY 和 ANTHROPIC_FOUNDRY_RESOURCE 環境變數。

Q: session 資料存在哪裡？

A: 本地存儲，agent/session.py 管理。使用 ct sessions 查看，ct --continue 繼續上一個。

Q: 報告輸出支援什麼格式？

A: Markdown（自動儲存）和 HTML（ct report publish）。HTML 報告：深色主題、響應式版面、inline CSS，無 CDN 依賴，可直接分享。也可匯出為 Jupyter notebook（ct export）。

Q: 如何新增自定義工具？

A: 遵循 registry 模式（見§3「工具 Registry 模式」），在 src/ct/tools/ 建立新 .py 檔案，使用 @registry.register() 裝飾器即可。

8. 進階技巧

進階查詢技巧

1# 指定最大工具呼叫次數（預設 30）
2ct --max-turns 50 "詳細分析這個化合物的所有面向"
3
4# 使用 @mention 指定工具
5ct "@structure_tools @literature 分析 EGFR inhibitor 的結合模式"
6
7# 使用 /agents 跑平行研究
8/agents 5 "Compare safety profiles of these 5 kinase inhibitors: ..."

資料集最佳實踐

1# 只下載需要的資料集（節省磁碟空間）
2ct data pull depmap     # ~2GB，標靶必需性分析
3ct data pull prism      # ~500MB，細胞存活篩選
4ct data pull msigdb     # ~50MB，通路分析
5
6# 設定資料路徑（有現有資料時）
7ct config set data.depmap /data/DepMap_24Q2/
8ct config set data.prism /data/PRISM_19Q4/

報告工作流

1# 批量轉換所有報告為 HTML
2for f in ~/.ct/reports/*.md; do ct report publish "$f"; done
3
4# 設定報告輸出目錄
5ct config set report.output_dir ~/drug-discovery-reports/

雲端 GPU 工具

需要 Modal 帳號設定：

1ct config set cloud.provider modal
2ct config set cloud.modal_token_id <your-token>
3# 然後可使用 AlphaFold2-multimer、RFdiffusion 等
4ct "Predict the complex structure of IKZF1 with this peptide: ..."

9. 整合進其他工作流

與 CI/CD 整合

1# .github/workflows/drug-analysis.yml
2- name: Run celltype analysis
3  env:
4    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
5  run: |
6    ct setup --api-key $ANTHROPIC_API_KEY
7    ct "Analyze compound ${{ inputs.compound_id }}" --output report.html

Python 程式碼整合

1# 直接呼叫 ct 的代理 runner
2from ct.agent.runner import AgentRunner
3from ct.agent.config import AgentConfig
4
5config = AgentConfig(model="claude-opus-4-6", max_turns=30)
6runner = AgentRunner(config)
7result = runner.run("What are the top degradation targets for CRBN?")
8print(result.summary)

MCP Server 整合

celltype-agent 提供 in-process MCP server，可以被其他支援 MCP 協議的客戶端整合：

1# 啟動 MCP server 模式（供其他工具連接）
2ct --mcp-server

與 Jupyter Notebook 整合

1# 在 ct 互動模式中匯出 session 為 notebook
2/export notebook session_20260518
3
4# 或直接從 CLI
5ct export notebook --session-id <id> --output analysis.ipynb

10. 重點摘要 Checklist

安裝驗證

ct --version 顯示 0.2.1+
ct doctor 無錯誤
ct setup 完成 API key 設定
ct "test query" 正常回應

資料準備

決定需要哪些資料集（DepMap / PRISM / L1000）
ct data pull <dataset> 或設定現有資料路徑
確認磁碟空間足夠（DepMap ~2GB）

工具準備

ct tool list 查看可用工具
需要本地 GPU 工具時：ct tool pull <tool>
需要雲端 GPU 時：設定 Modal 帳號

資安建議

使用環境變數管理 API key，不放入程式碼
生產環境使用 pipx install 而非 curl-pipe
敏感環境評估是否啟用 shell.py 工具
定期 ct --version 確認使用最新版本

11. 進一步閱讀

官方資源

官方網站：https://www.celltype.com/cli
GitHub：https://github.com/celltype/celltype-agent
PyPI：https://pypi.org/project/celltype-cli/
企業聯絡：hello@celltype.com

celltype-agent 完整教學指南

Contents

celltype-agent 完整教學指南

1. 專案定位與核心概念

什麼是 celltype-agent？

核心特點

適合對象

2. 安裝指南

系統需求

快速安裝（推薦）

手動安裝

開發環境安裝

認證設定

驗證安裝

3. 核心架構解析

目錄結構

代理執行模型

工具 Registry 模式

計算路由（本地 vs 雲端）

4. Helper Scripts 詳細用法

CLI 主要指令

互動模式指令

資料集腳本

5. 應用場景

場景一：標靶優先化（分子膠水研究）

場景二：聯合用藥策略

場景三：抗藥性生物標記

場景四：蛋白質結構預測

場景五：多代理平行研究

場景六：使用本地資料

6. 資安掃描報告

整體評估：🟡 中等風險（需注意幾個設計選擇）

🟢 低風險

🟡 中等風險

🔴 高風險

7. FAQ

8. 進階技巧

進階查詢技巧

資料集最佳實踐

報告工作流

雲端 GPU 工具

9. 整合進其他工作流

與 CI/CD 整合

Python 程式碼整合

MCP Server 整合

與 Jupyter Notebook 整合

10. 重點摘要 Checklist

安裝驗證

資料準備

工具準備

資安建議

11. 進一步閱讀

官方資源

相關技術

相關學術工具

Related Posts

Comments