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/marimomarimo 提供了一个实验性的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 ProtocolACP——一个语言无关的、基于 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 包装Claude3017npx zed-industries/claude-code-acpGemini3019npx google/gemini-cli --experimental-acpCodex3021npx zed-industries/codex-acpOpenCode3023npx opencode-ai acp源码中的AGENT_CONFIG还预留了第 5 个条目cursor端口 3025命令agent acp见 state.ts可在前端下拉中看到说明 Agent 列表仍在持续扩充中。Claude Code AgentClaude Code Agent 使用你的 Claude Code CLI 订阅 来协助编码任务。安装与登录# 安装 npm install -g anthropic-ai/claude-code # 登录 claude # 然后输入 /login连接命令 macOS/Linuxbash npx stdio-to-ws npx zed-industries/claude-code-acp --port 3017 Windowsbash npx stdio-to-ws cmd /c npx zed-industries/claude-code-acp --port 3017 Gemini AgentGoogle 的 Gemini Agent 提供有限的免费额度登录后可解锁更多高级功能。登录与认证方式请参阅 Gemini CLI 官方文档。连接命令 macOS/Linuxbash npx stdio-to-ws npx google/gemini-cli --experimental-acp --port 3019 Windowsbash npx stdio-to-ws cmd /c npx google/gemini-cli --experimental-acp --port 3019 Codex AgentOpenAI 的 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/Linuxbash npx stdio-to-ws npx zed-industries/codex-acp --port 3021 Windowsbash npx stdio-to-ws cmd /c npx zed-industries/codex-acp --port 3021 OpenCode AgentOpenCode 是一款开源、面向终端的 AI 编程 Agent同时支持 ACP 协议。安装# 安装 npm install -g opencode-ailatest # 安装后即可在命令行中使用与配置 opencode opencode连接命令 macOS/Linuxbash npx stdio-to-ws npx opencode-ai acp --port 3023 Windowsbash 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_linkMIME 类型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(fyour query)DuckDB或df mo.sql(fyour query, engineengine)其他引擎。这套机制保证了 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 requestsAgent 可能会请求读取或写入文件的权限。请在批准前仔细审查这些请求避免赋予超出预期的文件访问范围。会话限制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 条目会持续演进建议以本仓库最新文档为准。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考