Training an agent to reason inside a notebook
Jupyter Agent connects code execution, training data, and evaluation for analytical tasks.
The notebook is both an agent workspace and a record a human can review.
The Jupyter Agent project places a model inside a notebook where code and explanations can develop together. The follow-up work focuses on generating training examples, adapting a smaller model, and measuring performance on realistic data-science questions.
A notebook makes intermediate work visible: calculations, errors, tables, and revisions can all be inspected. That is valuable because an analytical answer can sound convincing while using the wrong data transformation. Better execution is not the same as guaranteed analytical correctness.
Explore the demo and the DABStep benchmark described in the source. For a trial, choose a dataset with known answers and review the intermediate cells, not only the final response. Keep sensitive data out of a public demonstration and use a controlled execution environment.
A notebook gives an agent an executable workspace
A notebook combines code, outputs and explanatory text in one document. For an AI agent, that can provide a useful loop: propose an analysis, execute it, inspect the result and revise the next step. The visible notebook can also help a human understand how the answer was produced.
The same flexibility introduces risks of confusion. Notebook cells can be run out of order, variables can retain old values, and a polished chart can be based on a hidden earlier state. An agent-generated notebook needs the same reproducibility discipline as a human-generated one.
Make the starting state explicit
Begin with a defined dataset and a clean runtime. Record where the data came from and which version is being analyzed. Avoid allowing the agent to infer the meaning of columns solely from convenient names; inspect types, missing values and a small sample first.
For a practical analysis task, write down the question and the intended output before generating code. “Explore this data” can produce interesting charts without answering the decision that motivated the work.
Treat execution as evidence, not authority
A cell that runs successfully has passed a software check, not necessarily an analytical one. The calculation may use the wrong denominator, join the wrong records or exclude an important group. Inspect the assumptions behind the code as well as its syntax.
Keep intermediate tables and simple sanity checks visible. Counts before and after a filter, totals after a join and a few manually checked examples can reveal errors that a final visualization hides.
Control the environment
Generated code should run with only the files and permissions needed for the analysis. A notebook task does not automatically require unrestricted access to the machine or network. Use time and resource limits so that an accidental large computation does not monopolize the environment.
External data and notebook text are inputs, not instructions that override the user’s task. This distinction matters when an agent reads arbitrary documents or datasets as part of its analysis.
Test whether the result can be repeated
Restart the runtime and run the notebook from top to bottom. If the result depends on an unrecorded manual step or a cell executed out of order, the notebook is not yet a reliable artifact. Preserve the dependencies and any random seeds that materially affect the result.
The useful promise of notebook agents is not automatic scientific correctness. It is a faster route from a question to an inspectable executable analysis. The value comes from keeping the reasoning, calculations and evidence visible enough that another person can challenge and reproduce the conclusion.
Source: Jupyter Agents: training LLMs to reason with notebooks ↗ · baptistecolle, hannayukhymenko, lvwerra. How we write
