marimo Agents 接入指南：通过 Agent Client Protocol 在聊天面板中内嵌 AI 编程助手-创锋一号

marimo Agents 接入指南：通过 Agent Client Protocol 在聊天面板中内嵌 AI 编程助手

【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo

marimo 提供了一个实验性的Agents功能：通过 Agent Client Protocol 展开，并结合仓库前端与运行时源码，完整讲解四种受支持 Agent 的安装、连接、配置与排障方法。

[!WARNING] Agents 目前是实验性功能，处于活跃开发阶段，相关功能与 API 可能随时变化。

[!TIP] 如果你的诉求是“在终端里用 Agent CLI 驱动笔记本”，大多数用户应优先尝试 marimo pair——它能让 Claude Code 等 Agent CLI 从终端完整访问正在运行的笔记本。本文介绍的集成方式则是把 Agent嵌入 marimo 编辑器内部的聊天面板，两者定位不同，可互补使用。

工作原理：ACP 协议与浏览器侧的 WebSocket 桥接

marimo Agents 的底层是 Agent Client Protocol（ACP）——一个语言无关的、基于 JSON-RPC 的开放协议，用于在 Agent 与客户端（编辑器、IDE）之间建立标准化通信。

从仓库前端源码可以还原出完整的调用链：

各 Agent 通过 stdio-to-ws 动态拼接ws(s)://<当前主机名>:<端口>/message的地址——它使用当前页面的 hostname，因此当 marimo 通过反向代理或远程 IP 访问时同样可达。
浏览器侧通过use-acp客户端与 Agent 建立连接。在 agent-panel.tsx 中可以看到，ACP 客户端在初始化时声明了文件系统能力（readTextFile/writeTextFile），文件读写最终经由 marimo 的请求通道（sendFileDetails/sendUpdateFile）完成——这正是 Agent 能读写笔记本文件的关键一环。
连接建立后，客户端会尝试initialize（协议版本 1），若 Agent 返回authMethods，则自动发起authenticate流程；用户随后重启会话即可完成登录（对应 agent-panel.tsx 中的initAndAuth逻辑）。
会话创建时以当前笔记本所在目录为工作目录（cwd），并支持通过newSession/loadSession创建或恢复会话、选择模型、切换 Agent Mode（详见agent-panel.tsx中的handleNewSession/handleResumeSession）。

受支持的 Agent 与连接命令

marimo 目前内置了 4 种受支持的 Agent。前端 state.ts 中的AGENT_CONFIG集中定义了每种 Agent 的端口与启动命令模板：

Agent	端口	启动命令（经 stdio-to-ws 包装）
Claude	3017	`npx @zed-industries/claude-code-acp`
Gemini	3019	`npx @google/gemini-cli --experimental-acp`
Codex	3021	`npx @zed-industries/codex-acp`
OpenCode	3023	`npx opencode-ai acp`

源码中的AGENT_CONFIG还预留了第 5 个条目cursor（端口 3025，命令agent acp，见 state.ts），可在前端下拉中看到，说明 Agent 列表仍在持续扩充中。

Claude Code Agent

Claude Code Agent 使用你的 Claude Code CLI 订阅来协助编码任务。

安装与登录：

# 安装 npm install -g @anthropic-ai/claude-code # 登录 claude # 然后输入 /login

连接命令：

=== "macOS/Linux"

```bash npx stdio-to-ws "npx @zed-industries/claude-code-acp" --port 3017 ```

=== "Windows"

```bash npx stdio-to-ws "cmd /c npx @zed-industries/claude-code-acp" --port 3017 ```

Gemini Agent

Google 的 Gemini Agent 提供有限的免费额度，登录后可解锁更多高级功能。

登录与认证方式请参阅 Gemini CLI 官方文档。

连接命令：

=== "macOS/Linux"

```bash npx stdio-to-ws "npx @google/gemini-cli --experimental-acp" --port 3019 ```

=== "Windows"

```bash npx stdio-to-ws "cmd /c npx @google/gemini-cli --experimental-acp" --port 3019 ```

Codex Agent

OpenAI 的 Codex Agent 使用 Codex CLI，通过@zed-industries/codex-acp适配器接入。

安装与登录：

# 安装 Codex CLI npm install -g @openai/codex # 或：brew install --cask codex # 登录（或设置 OPENAI_API_KEY / CODEX_API_KEY 环境变量） codex

连接命令：

=== "macOS/Linux"

```bash npx stdio-to-ws "npx @zed-industries/codex-acp" --port 3021 ```

=== "Windows"

```bash npx stdio-to-ws "cmd /c npx @zed-industries/codex-acp" --port 3021 ```

OpenCode Agent

OpenCode 是一款开源、面向终端的 AI 编程 Agent，同时支持 ACP 协议。

安装：

# 安装 npm install -g opencode-ai@latest # 安装后即可在命令行中使用与配置 opencode opencode

连接命令：

=== "macOS/Linux"

```bash npx stdio-to-ws "npx opencode-ai acp" --port 3023 ```

=== "Windows"

```bash npx stdio-to-ws "cmd /c npx opencode-ai acp" --port 3023 ```

OpenCode 的模型配置：OpenCode 支持众多模型，包括通过 Ollama 运行的本地模型，并可通过配置文件进行配置：

{ "$schema": "https://opencode.ai/config.json", "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:11434/v1" }, "models": { "<model_name>": { "tools": true } } } } }

如果你选择 Ollama 本地模型，务必把最大上下文长度（max context length）设置得远高于默认的 4K。OpenCode 同样支持配置远程模型（如 OpenRouter 托管的模型或 Zen 服务），更多 Provider 配置方式见 OpenCode provider 文档。

连接 Agent 的五步流程

启动 Agent 服务器：在终端运行上面对应 Agent 的连接命令；
开启功能开关：在设置菜单的 “Lab” 区域启用 Agents 功能开关；
打开 Agent 面板：点击 marimo 侧边栏中的 Agents 图标；
选择 Agent：从下拉菜单中选择要使用的 Agent；
开始对话：Agent 现在可以读取并修改你的笔记本了。

[!TIP]终端集成：如果 marimo 已启用终端（terminal）能力，你可以直接在 Agent 面板里点击终端按钮运行 Agent 连接命令，无需切换到外部终端。这一交互在前端 agent-docs.tsx 中有对应实现——面板内展示连接命令的同时提供“复制”与“发送到终端”两个按钮，后者通过sendCommand把命令直接投递给内置终端。

[!TIP]Agent 修改后自动运行：默认情况下，当 Agent 修改笔记本后，相关单元格只会被标记为 stale（过期）而不会自动执行。若希望 Agent 保存变更后立即看到运行结果，可在pyproject.toml中添加如下配置：

[tool.marimo.runtime] watcher_on_save = "autorun"

该配置项在 marimo/_config/config.py 中被定义为Literal["lazy", "autorun"]，默认值为"lazy"（只把受影响的单元格标记为 stale）。切换为"autorun"后，Agent 保存文件会触发受影响的单元格自动运行，获得更流畅的协作体验。

浏览器侧会话管理与权限机制

从源码结构看，Agent 面板的会话状态由 state.ts 中的agentSessionStateAtom统一管理（持久化键为marimo:acp:sessions:v1），每个会话（tab）绑定一个 Agent 并记录外部会话 ID 与所选模型：

单会话限制：MAX_SESSIONS = 1，且AGENT_CONFIG中所有 Agent 的sessionSupport均为"single"——当你在同一 Agent 下新建会话时，旧会话会被覆盖替换（见 state.ts 的addSession逻辑），这与官方文档“每个 Agent 目前仅支持一个会话”的说明一致。
会话恢复：连接建立后，面板会优先尝试loadSession恢复之前的会话，失败则回退为newSession新建会话（见 agent-panel.tsx）。
权限请求：Agent 在读取或写入文件时，会通过 ACP 的权限机制弹出请求（pendingPermission/resolvePermission），面板顶部会展示PermissionRequest供用户逐条审批（见 agent-panel.tsx）。

Agent 如何正确编辑 marimo 笔记本：内置规则提示词

为了让外部 Agent 写出符合 marimo 响应式语义的代码，marimo 会在首次发送提示词时，把当前笔记本文件（resource_link，MIME 类型text/x-python）连同内置规则文件marimo_rules.md一起注入会话（见 agent-panel.tsx）。

这份规则提示词定义在 frontend/src/components/chat/acp/prompt.ts 中，核心约束包括：

只编辑@app.cell装饰器内部：Agent 修改笔记本时不得触碰 marimo 自动维护的 cell 参数与返回值，每个编辑只需给出如下形态的完整代码块：

@app.cell def _(): <your code here> return

遵守 marimo 响应式语义：单元格在其依赖变化时自动执行；变量不能跨单元格重复声明；笔记本构成有向无环图（DAG）；单元格最后一个表达式会被自动展示；UI 元素是响应式的并会自动更新笔记本。
代码规范：所有代码必须完整可运行；首个单元格统一导入import marimo as mo；禁止跨单元格重声明变量；保证依赖图无环；不要在 markdown / SQL 单元格内写注释；禁止使用global。
UI 与可视化实践：通过.value访问 UI 元素值（且不能在定义 UI 元素的同一单元格内读取其值）；matplotlib用plt.gca()作为末表达式而非plt.show()；plotly/altair直接返回图表对象。
SQL 实践：优先使用 marimo 的 SQL 单元格，例如df = mo.sql(f"""<your query>""")（DuckDB）或df = mo.sql(f"""<your query>""", engine=engine)（其他引擎）。

这套机制保证了 Agent 生成/修改的代码与 marimo 的响应式执行模型兼容，避免产生循环依赖、重复定义等 notebook 特有错误。

单元格“过期”追踪：Agent 读取状态的运行时实现

在运行时侧，marimo 为每个 Kernel 维护了一个长期存活的Agent状态对象（见 marimo/_runtime/agent.py），其中的AgentReadTracker按单元格记录“Agent 已观测到的最高版本号”：

record_read(cell_id, version)在 Agent 读取单元格时更新其版本；
has_read(cell_id, current_version)判断 Agent 是否已读取过当前版本；
get_stale_cells(doc)遍历笔记本所有单元格，把“Agent 尚未读取且包含非空代码”的单元格判定为 stale（空单元格不会覆盖任何内容，因此永远不算 stale，见 agent.py）。

这套机制正是“Agent 修改笔记本后，未读过的单元格会被标记为 stale”这一默认行为的运行时基础，也解释了为什么切换到watcher_on_save = "autorun"能带来更即时的反馈。

自定义 Agent 与常见问题排查

自定义 Agent：目前官方文档标注自定义 Agent 支持“即将到来”（Support for custom agents is coming soon），届时可连接你自己的 ACP 兼容 Agent。在此之前，请使用内置的四种 Agent。

连接问题（Connection issues）：在 marimo 中连接之前，请确保 Agent 服务器正在正确端口上运行。可先用浏览器访问ws://<host>:<port>/message所在地址或检查端口占用来验证。

权限请求（Permission requests）：Agent 可能会请求读取或写入文件的权限。请在批准前仔细审查这些请求，避免赋予超出预期的文件访问范围。

会话限制（Session limits）：当前每个 Agent 仅支持一个会话，以保证最佳性能。新建会话会覆盖同 Agent 的旧会话（源码见 state.ts 的会话替换逻辑）。

小结

marimo 的 Agents 功能把 Claude Code、Gemini、Codex、OpenCode 等主流 AI 编程 Agent 通过标准化的 ACP 协议接入编辑器聊天面板：终端一条npx stdio-to-ws ...命令启动 Agent 服务器，设置里开启功能开关，即可在面板中直接让 Agent 读写笔记本。结合marimo_rules.md规则注入、AgentReadTracker单元格过期追踪与watcher_on_save自动运行配置，Agent 的协作体验可以在保证 notebook 响应式语义正确的前提下，做到“改完即跑、所见即得”。由于该功能仍处实验阶段，API 与内置 Agent 列表（含源码中预留的 cursor 条目）会持续演进，建议以本仓库最新文档为准。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析