Agent Mode

1. Switch to Agent Mode

Open the CellPilot chat box and type one of the following commands:

Switch to agent mode
Use agent mode
Change chat mode to Agent

CellPilot will ask which API provider to use. Supported providers are Gemini, ChatGPT, Claude, Groq, and OpenRouter. After you choose a provider, paste your API key when prompted, then choose a model from the model list.

To leave Agent Mode, type:

Back to intent mode
Exit agent mode

2. What Agent Mode can do

Agent Mode can plan and run CellPilot tools for single-cell, spatial, ATAC, and multiome data. It is especially useful when a request needs multiple steps, for example finding markers first and then using those markers to suggest an annotation.

1. For single-cell data, it can annotate one cluster or annotate all clusters from marker genes.
2. For spatial data, it can interpret a selected tissue region by comparing that region against the rest of the tissue.
3. For spatial data with multiple selected regions, it can run ligand-receptor style cell-cell interaction analysis and summarize the result.
4. For multiome data, it can route commands to RNA, ATAC, or WNN views when the task is ambiguous.

Expensive or object-changing actions, such as broad reanalysis, BANKSY segmentation, WNN integration, or cluster renaming, may ask for confirmation before running.

3. Example dataset for this tutorial

The spatial examples below use the same 10x Genomics Visium HD mouse kidney dataset from the Visium HD tutorial. Load the Space Ranger output folder first, then add the tissue image if you want to use the histology overlay.

Open the 10x Genomics Visium HD mouse kidney dataset page

mkdir -p visiumhd_mouse_kidney
cd visiumhd_mouse_kidney

curl -O https://cf.10xgenomics.com/samples/spatial-exp/4.0.1/Visium_HD_Mouse_Kidney/Visium_HD_Mouse_Kidney_tissue_image.btf

For your own data, load the standard Space Ranger output folder directly. The command above is only for the public demo image.

4. Single-cell cluster annotation

After loading a single-cell dataset and running clustering, Agent Mode can find markers and suggest cell type labels. It can annotate one cluster or all clusters.

Annotate cluster 3
What cell type is cluster 5?
Identify all clusters
Annotate every cluster

For all-cluster annotation, CellPilot first finds markers for each cluster, sends the marker summaries to the selected agent provider, and then shows an annotation table in the Analysis View. If labels look reasonable, CellPilot can ask whether you want to rename the clusters with those labels.

5. Find clusters for a known cell type

You can also ask the agent to search for a biological cell type. The agent chooses a focused marker panel, CellPilot scores the real dataset using those markers, and the result ranks candidate clusters.

Which cluster is proximal tubule?
Find podocyte clusters
Do you know which cluster is endothelial cells?
Find immune cell clusters

Use this as a guided marker search, then validate the suggested clusters with marker plots and dot plots.

6. Selected spatial region annotation

For spatial datasets such as Visium HD, Xenium, MERFISH, or CosMx, open Spatial View and select a region with the rectangle or freehand selection tool. Then ask the agent what that area likely represents.

What is this region?
Annotate the selected region
What cell types are in this selected area?
Find markers for the selected spatial region

CellPilot compares the selected cells against the rest of the tissue, returns marker genes, and lets the agent interpret the region. If a histology image is loaded, the selected region context can also include the ROI image.

7. Cell-cell interaction across selected regions

To run cell-cell interaction analysis, select at least two spatial regions in Spatial View. Each selected region should contain at least a few cells. Then ask Agent Mode to run the interaction workflow.

Run cell-cell interaction analysis across selected regions
Run ligand-receptor analysis between the selected areas
Compare cell-cell communication across these regions

CellPilot runs the ligand-receptor style analysis across the selected regions and the agent adds an interpretation. The agent also annotates each selected region from region marker genes before discussing likely communication patterns.

8. Other useful Agent Mode requests

Agent Mode can also plan common analysis and visualization tasks while keeping the work inside CellPilot.

Plot Nphs2 on the spatial view
Find markers for cluster 6 and suggest an annotation
Run BANKSY region segmentation
Show current analysis parameters
Run WNN analysis for this multiome dataset
Find differential genes for cluster 2 between sample 1 and sample 2

When the request is ambiguous, CellPilot will ask a short follow-up question or ask you to choose the RNA, ATAC, WNN, or spatial target.

9. Review and confirm results

Agent Mode is designed to help biologists avoid writing code, but annotations should still be reviewed. Use the marker tables, dot plots, feature plots, spatial plots, and original histology context to validate suggested labels before using them in figures or manuscripts.