Use pyobservablejs with agents

The installed package includes an Agent Skill, a set of instructions and recipes for constructing notebooks, selecting views, synchronizing values, and reading browser results. Read it in the same Python environment as your notebook so the instructions match the installed API.

import observablejs.agent as agent

skill = agent.agent_skill()
print(skill.body)
print(skill.file("references/workflows.md").read_text())

Find instructions from a terminal

agent-plugins locates agent resources installed with Python packages. It is included with pyobservablejs:

agent-plugins locate pyobservablejs
agent-plugins list --json

locate prints the installed plugin directory. list --json reports the plugins and skill instruction files in the current environment. In a uv project, run these commands with uv run to use that project's environment.

Inspect the installed API

import observablejs as obs
import observablejs.agent as agent

help(agent)
help(obs.Notebook)
help(obs.Notebook.view)

help(agent) includes a working notebook example and installed resource paths. Use agent.agent_plugin().tree() to inspect the packaged files.

API	Result
agent.agent_plugin()	The installed agent_plugins.Plugin.
agent.agent_skill()	The agent_plugins.Skill named pyobservablejs.
skill.body	Instructions as Markdown.
skill.file("references/workflows.md")	A checked path to the packaged workflow recipes.

Resource lookup raises agent_plugins.AgentPluginError when installed plugin metadata or a requested resource is unavailable. Reinstall pyobservablejs in the active environment if the packaged files are missing.

Work in a live marimo notebook

marimo is a reactive Python notebook host. marimo pair connects an agent to its live kernel, where it can inspect variables, edit cells, and run the notebook. Use its connection instructions before operating on live cells.

With marimo 0.24.0 or newer, a connected agent can discover pyobservablejs through marimo's code-mode API:

import marimo._code_mode as cm

print(cm.capabilities()["pyobservablejs"])

The result points to observablejs.agent. Import it and read the packaged skill before constructing or changing an Observable view. Use help(cm) for the installed notebook-editing contract.

Display the view in the notebook before reading view.state. Browser evaluation starts when the host mounts it. In a marimo readback cell, reference view.value to subscribe to updates, then inspect the current snapshot. See Read browser results for readiness, named values, and error handling.

Fetch documentation on demand

• llms.txt maps tasks to guide, example, and reference pages.
• llms-full.txt combines the published documentation as Markdown.

Use installed skills and help() for the package version in the notebook. The website describes the published documentation version.

Check browser failures

In Jupyter, display the view and call await view.ready() in a later cell. After changing Python variables, the checkpoint waits for that update before returning state. Browser failures raise custom Python exceptions with source, component, operation, stack, and cause details.

In a reactive marimo cell, use view.value followed by view.raise_for_errors(). Let the exception reach the agent's execution result. obs.errors.NotebookError identifies authored source failures. obs.errors.WidgetError identifies runtime or adapter failures. See Errors and diagnostics for the exception hierarchy and structured view.diagnostics records.