Skip to main content
Glama

run_cell

Submit an IPython cell to a persistent kernel so variables and imports carry over between cells, with timing and output controls for long-running work.

Instructions

向持久 IPython kernel 提交一个 IPython cell。

请你使用 IPython 的思想来优雅使用本系列工具。

输入

一格 IPython cell,变量、导入和其他 namespace 状态与当前持久 IPython 会话中的后续 cell 共享。

loommux cell magic

cell 第一行写 %%loommux,给这一次调用加参数;选项只作用于这一个 cell, 下一行可以接另一个 cell magic,例如 %%bash::

%%loommux --wait 260 --silence 35
%%bash
pnpm exec playwright test

等待有两个计时器,对应 HTTP 客户端的总超时与 read timeout(CI 里是 job timeout 与 no_output_timeout):

--wait SECONDS:这次调用最多等多久; --silence SECONDS:cell 连续这么久没有任何输出就提前返回,从提交起计,每来一条输出就重新计时。

cell 跑完立即返回;计时器先到时,结果写明 running 与原因,附最后几行输出。 到点只交还控制权,cell 照常运行:接着用 wait 等(同样两个计时器),或 read_output、interrupt。

不写时两个都是 10 秒,几秒内结束的 cell 不用写。要跑更久,就按这次具体在跑的东西估两个整数秒, 不写 30、120、600 这类凑整的数:--wait 是略高于预期、超过就该回来看看的上限; --silence 是健康运行里两行输出之间最长的间隔。上面的 e2e 上次跑了 212 秒,最慢的用例 23 秒; 训练 12 个 epoch、每个约 280 秒才打一行时,写 --wait 3500 --silence 320。 只写 --wait 时静默仍是 10 秒,安静的长任务会在 10 秒处先回来。

每个结果第一行写着这次执行跑了多久,如 In [7] · 54.3 s:,还在跑时是从提交到现在; 下一次估计照着它修正。

--full-output:让本次 execution 在终态时返回完整 combined 正文,突破默认 5,000-token 阈值限制; 在明确需要完整阅读某些文件、资料时使用,避免反复阅读的开销。

--kernel NAME 写另一个 kernel 的名字,把这个 cell 交给它::

%%loommux --kernel build --wait 75 --silence 25
%%bash
uv run pytest

build 是这个会话主 kernel 名下的子 kernel,不存在时首次使用就开出, 跟着主 kernel 活、跟着它回收;子 kernel 的名字只在各自的主 kernel 名下唯一, 别的主 kernel 名下的写全称 /主kernel名/build。 这个 cell 就是 loommux.create("build") 再在它上面 run_cell,在这里等它、接着它的输出; 所以中断这个 cell,build 的这次执行也被中断。 每个 kernel 里都有 loommux:守护进程的客户端,好比 docker 命令之于 dockerd。 守护进程管 kernel 的生死与名字:列出、查找、开子 kernel、改名、回收; loommux["build"] 取到的 kernel 有与这组工具同名同参的方法,你对主 kernel 做的事,对任何一台都能做。 细节在对象上:loommux?、help(loommux)。

什么时候用呢?

  1. 同时想利用Kernel本身(如果Shellwork合适优先使用)去跑长任务的同时,还想要使用主Kernel去做别的事情使用。

  2. 想要保持主Kernel命名空间干净,临时去子Kernel做探索、尝试、测试……完成后回收临时Kernel。 如果你要做的事情本身就是阻塞当前的这个任务,那么请只使用主Kernel.

主 kernel

第一个 cell 用 --attach 名字 --create 给它命名意味着向 loommux 申请持久资源,最长24小时动态刷新。 名字必须使用描述这次任务的一个短语,不带空格::

%%loommux --attach 主kernel绑定设计 --create
import pandas as pd

--attach 名字 可重新切换会曾命名到的持久资源。 任务变了,在任意 cell 里顺手写 loommux.rename(loommux.self, "新名字")。

图像展示

使用 IPython display() 即可看图, 对 PNG、JPEG、WEBP 或单帧 GIF 图像有效

执行编号与后续操作

提交成功可以获得一个 execution。后续工具使用它定位当前持久 IPython 会话中的这次执行。

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "freeform": "<freeform>"
    },
    "name": "run_cell"
  }
}

Input Schema

NameRequiredDescriptionDefault
freeformYes原始 IPython cell 源码文本。

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.13

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: it states the two timers (--wait and --silence, both defaulting to 10 seconds), that reaching a timer only returns control while the cell keeps running, that --full-output raises the default 5,000-token combined-body cap, that interrupting this cell interrupts the child kernel's execution, and that a named resource lives up to 24 hours. It even describes the first line of each result (e.g. "In [7] · 54.3 s:") so the agent can recalibrate estimates. Remaining gaps, such as error/exception formatting or concurrency limits across kernels, keep it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and the sections are labeled, which helps navigation. However, the text is very long and includes material not needed to invoke run_cell, such as the docker-versus-dockerd analogy, renaming conventions, and pointers to help(loommux), which dilute the operational content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema and no annotations, yet the description covers what an agent needs: return shape on completion versus timeout, the execution handle used by follow-up tools, output size limits, kernel targeting and lifecycle, and image display via display(). Nothing essential for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents the single freeform parameter at 100% coverage as raw IPython cell source, so the baseline is 3. The description goes well beyond that by specifying what belongs inside the cell: the %%loommux cell magic on the first line, its options (--wait, --silence, --full-output, --kernel, --attach --create), and that a second cell magic such as %%bash may follow. It never names the parameter itself, so it is strong but not exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first line states a specific verb and resource: submit an IPython cell to a persistent IPython kernel, with namespace state shared across subsequent cells. It further distinguishes the tool from siblings by explaining that continuation goes through wait, read_output, or interrupt, so an agent can tell which tool owns which phase of execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The "什么时候用呢?" section gives explicit when-to-use conditions for child kernels versus the main kernel, including an exclusion rule: if the work simply blocks the current task, use only the main kernel. It also routes continuation and cancellation to named siblings (wait, read_output, interrupt) with the conditions that select each.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.