Skip to content
Back to search

jupyter-ai-agents

πŸͺ πŸ€– AI Agents with πŸ”§ MCP tools and 🧰 Skills for JupyterLab β€” Chat with your Notebook and execute code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/datalayer--jupyter-ai-agents/badge.svg)](/listings/datalayer--jupyter-ai-agents)

HTML

<a href="/listings/datalayer--jupyter-ai-agents"><img src="/api/listings/datalayer--jupyter-ai-agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Currently, we support **Anthropic Claude Sonnet 4.0** as the AI model. To get started:

1. **Set up your environment:**

   export ANTHROPIC_API_KEY='your-api-key-here'

2. **Install Jupyter AI Agents:**

   pip install jupyter_ai_agents
   pip uninstall -y pycrdt datalayer_pycrdt
   pip install datalayer_pycrdt==0.12.17

3. **Launch JupyterLab with the required configuration:**

   jupyter lab

4. **Access the chat interface** through the right panel in JupyterLab.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 355 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!--
  2. ~ Copyright (c) 2024-2025 Datalayer, Inc.
  3. ~
  4. ~ BSD 3-Clause License
  5. -->
  6. [![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai)
  7. [![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
  8. # πŸͺ πŸ€– Jupyter AI Agents
  9. [![Github Actions Status](https://github.com/datalayer/jupyter-ai-agents/workflows/Build/badge.svg)](https://github.com/datalayer/jupyter-ai-agents/actions/workflows/build.yml)
  10. [![PyPI - Version](https://img.shields.io/pypi/v/jupyter-ai-agents)](https://pypi.org/project/jupyter-ai-agents)
  11. πŸͺ ✨ AI Agents for JupyterLab with πŸ› οΈ MCP tools - Chat interface for intelligent notebook interaction, code execution, and workspace management.
  12. ## πŸ’¬ Chat Interface
  13. Experience seamless AI-powered assistance directly within JupyterLab through our intuitive chat interface:
  14. ![Jupyter AI Agents Chat 1](https://images.datalayer.io/product/jupyter-ai-agents/jupyterlab-example-1.png)
  15. The chat interface is built using [Pydantic AI](https://github.com/pydantic/pydantic-ai) for robust AI agent orchestration and [Vercel AI Elements](https://github.com/vercel/ai-elements) for the user interface components.
  16. ### MCP Server Integration
  17. By default, the [Jupyter MCP Server](https://github.com/datalayer/jupyter-mcp-server) is started as a Jupyter server extension, providing access to all Jupyter MCP server tools directly through the chat interface. This enables the AI agent to interact with notebooks, execute code, manage files, and perform various Jupyter operations seamlessly.
  18. ![Jupyter AI Agents Chat 2](https://assets.datalayer.tech/jupyter-ai-agents/jupyter-ai-agents-chat-2.png)
  19. ### Getting Started with Chat
  20. Currently, we support **Anthropic Claude Sonnet 4.0** as the AI model. To get started:
  21. 1. **Set up your environment:**
  22. ```bash
  23. export ANTHROPIC_API_KEY='your-api-key-here'
  24. ```
  25. 2. **Install Jupyter AI Agents:**
  26. ```bash
  27. pip install jupyter_ai_agents
  28. pip uninstall -y pycrdt datalayer_pycrdt
  29. pip install datalayer_pycrdt==0.12.17
  30. ```
  31. 3. **Launch JupyterLab with the required configuration:**
  32. ```bash
  33. jupyter lab
  34. ```
  35. 4. **Access the chat interface** through the right panel in JupyterLab.
  36. ### What's Coming Next
  37. We're actively working on expanding the capabilities of Jupyter AI Agents:
  38. - πŸš€ **More LLM Providers**: Integration with additional AI model providers
  39. - βš™οΈ **MCP Configuration**: Enhanced MCP server configuration options
  40. - πŸ”§ **Extended Tool Access**: Chat access to tools from other MCP servers
  41. - πŸ› οΈ **Enhanced Features**: And much more!
  42. Check out our [GitHub Issues](https://github.com/datalayer/jupyter-ai-agents/issues) to see what we're working on. **Contributions are welcome!**
  43. > **Note**: The documentation at https://jupyter-ai-agents.datalayer.tech will be updated soon to reflect the new chat features and capabilities.
  44. <details>
  45. <summary><strong>πŸ–₯️ CLI Usage</strong></summary>
  46. ## CLI Usage
  47. You can also use Jupyter AI Agents through the command line interface for automated notebook operations.
  48. ![Jupyter AI Agents CLI](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-prompt-demo-terminal.gif)
  49. ### Basic Installation
  50. To install Jupyter AI Agents, run the following command:
  51. ```bash
  52. pip install jupyter_ai_agents
  53. pip uninstall -y pycrdt datalayer_pycrdt
  54. pip install datalayer_pycrdt==0.12.17
  55. ```
  56. Or clone this repository and install it from source:
  57. ```bash
  58. git clone https://github.com/datalayer/jupyter-ai-agents
  59. cd jupyter-ai-agents
  60. pip install -e .
  61. ```
  62. ### JupyterLab Setup
  63. The Jupyter AI Agents can directly interact with JupyterLab. The modifications made by the Jupyter AI Agents can be seen in real-time thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html). Make sure you have JupyterLab installed with the Collaboration extension:
  64. ```bash
  65. pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2
  66. ```
  67. We ask you to take additional actions to overcome limitations and bugs of the pycrdt library. Ensure you create a new shell after running the following commands:
  68. ```bash
  69. pip uninstall -y pycrdt datalayer_pycrdt
  70. pip install datalayer_pycrdt==0.12.17
  71. ```
  72. ### Examples
  73. Jupyter AI Agents provides CLI commands to help your JupyterLab session using **Pydantic AI agents** with **Model Context Protocol (MCP)** for tool integration.
  74. Start JupyterLab, setting a `port` and a `token` to be reused by the agent, and create a notebook `notebook.ipynb`.
  75. ```bash
  76. # make jupyterlab
  77. jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN
  78. ```
  79. Jupyter AI Agents supports multiple AI model providers (more information can be found on [this documentation page](https://jupyter-ai-agents.datalayer.tech/models/)).
  80. ### API Keys Configuration
  81. Set the appropriate API key for your chosen provider:
  82. **OpenAI:**
  83. ```bash
  84. export OPENAI_API_KEY='your-api-key-here'
  85. ```
  86. **Anthropic:**
  87. ```bash
  88. export ANTHROPIC_API_KEY='your-api-key-here'
  89. ```
  90. **Azure OpenAI:**
  91. ```bash
  92. export AZURE_OPENAI_API_KEY='your-api-key-here'
  93. export AZURE_OPENAI_ENDPOINT='https://your-resource.openai.azure.com'
  94. export AZURE_OPENAI_API_VERSION='2024-08-01-preview' # optional
  95. ```
  96. **Important for Azure OpenAI:**
  97. - The `AZURE_OPENAI_ENDPOINT` should be just the base URL (e.g., `https://your-resource.openai.azure.com`)
  98. - Do NOT include `/openai/deployments/...` or query parameters in the endpoint
  99. - The deployment name is specified via the `--model-name` parameter
  100. - See `.env.azure.example` for a complete configuration template
  101. **Other providers:**
  102. ```bash
  103. export GOOGLE_API_KEY='your-api-key-here' # For Google/Gemini
  104. export COHERE_API_KEY='your-api-key-here' # For Cohere
  105. export GROQ_API_KEY='your-api-key-here' # For Groq
  106. export MISTRAL_API_KEY='your-api-key-here' # For Mistral
  107. # AWS credentials for Bedrock
  108. export AWS_ACCESS_KEY_ID='your-key'
  109. export AWS_SECRET_ACCESS_KEY='your-secret'
  110. export AWS_REGION='us-east-1'
  111. ```
  112. ### Model Specification
  113. You can specify the model in two ways:
  114. 1. **Using `--model` with full string** (recommended):
  115. ```bash
  116. --model "openai:gpt-4o"
  117. --model "anthropic:claude-sonnet-4-0"
  118. --model "azure-openai:deployment-name"
  119. ```
  120. 2. **Using `--model-provider` and `--model-name`**:
  121. ```bash
  122. --model-provider openai --model-name gpt-4o
  123. --model-provider anthropic --model-name claude-sonnet-4-0
  124. ```
  125. Supported providers: `openai`, `anthropic`, `azure-openai`, `github-copilot`, `google`, `bedrock`, `groq`, `mistral`, `cohere`
  126. ### Prompt Agent
  127. Create and execute code based on user instructions:
  128. ```bash
  129. # Using full model string (recommended)
  130. jupyter-ai-agents prompt \
  131. --url http://localhost:8888 \
  132. --token MY_TOKEN \
  133. --model "anthropic:claude-sonnet-4-0" \
  134. --path notebook.ipynb \
  135. --input "Create a matplotlib example"
  136. # Using provider and model name
  137. jupyter-ai-agents prompt \
  138. --url http://localhost:8888 \
  139. --token MY_TOKEN \
  140. --model-provider anthropic \
  141. --model-name claude-sonnet-4-0 \
  142. --path notebook.ipynb \
  143. --input "Create a pandas dataframe with sample data and plot it"
  144. ```
  145. ![Jupyter AI Agents - Prompt](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-prompt-demo-terminal.gif)
  146. ### Explain Error Agent
  147. Analyze and fix notebook errors:
  148. ```bash
  149. jupyter-ai-agents explain-error \
  150. --url http://localhost:8888 \
  151. --token MY_TOKEN \
  152. --model "anthropic:claude-sonnet-4-0" \
  153. --path notebook.ipynb \
  154. --current-cell-index 5
  155. ```
  156. ![Jupyter AI Agents - Explain Error](https://assets.datalayer.tech/jupyter-ai-agent/ai-agent-explainerror-demo-terminal.gif)
  157. ### REPL Mode (Interactive)
  158. For an interactive experience with direct access to all Jupyter MCP tools, use the REPL mode:
  159. ```bash
  160. jupyter-ai-agents repl \
  161. --url http://localhost:8888 \
  162. --token MY_TOKEN \
  163. --model "anthropic:claude-sonnet-4-0"
  164. ```
  165. In REPL mode, you can directly ask the AI to:
  166. - List notebooks in directories
  167. - Read and analyze notebook contents
  168. - Execute code in cells
  169. - Insert new cells
  170. - Modify existing cells
  171. - Install Python packages
  172. Example REPL interactions:
  173. ```
  174. > List all notebooks in the current directory
  175. > Create a new notebook called analysis.ipynb
  176. > In analysis.ipynb, create a cell that imports pandas and loads data.csv
  177. > Execute the cell and show me the first 5 rows
  178. > Add a matplotlib plot showing the distribution of the 'age' column
  179. ```
  180. The REPL provides special commands:
  181. - `/exit`: Exit the session
  182. - `/markdown`: Show last response in markdown format
  183. - `/multiline`: Toggle multiline input mode (use Ctrl+D to submit)
  184. - `/cp`: Copy last response to clipboard
  185. You can also use a custom system prompt:
  186. ```bash
  187. jupyter-ai-agents repl \
  188. --url http://localhost:8888 \
  189. --token MY_TOKEN \
  190. --model "anthropic:claude-sonnet-4-0" \
  191. --system-prompt "You are a data science expert specializing in pandas and matplotlib."
  192. ```
  193. ### Prompt Agent
  194. Create and execute code based on user instructions:
  195. ```bash
  196. # Using full model string (recommended)
  197. jupyter-ai-agents prompt \
  198. --url http://localhost:8888 \
  199. --token MY_TOKEN \
  200. --model "anthropic:claude-sonnet-4-0" \
  201. --path notebook.ipynb \
  202. --input "Create a matplotlib example"
  203. # Using provider and model name
  204. jupyter-ai-agents prompt \
  205. --url http://localhost:8888 \
  206. --token MY_TOKEN \
  207. --model-provider anthropic \
  208. --model-name claude-sonnet-4-0 \
  209. --path notebook.ipynb \
  210. --input "Create a pandas dataframe with sample data and plot it"
  211. ```
  212. ### Explain Error Agent
  213. Analyze and fix notebook errors:
  214. ```bash
  215. jupyter-ai-agents explain-error \
  216. --url http://localhost:8888 \
  217. --token MY_TOKEN \
  218. --model "anthropic:claude-sonnet-4-0" \
  219. --path notebook.ipynb \
  220. --current-cell-index 5
  221. ```
  222. ## Uninstall
  223. ### About the Technology
  224. Jupyter AI Agents empowers **AI** models to **interact** with and **modify Jupyter Notebooks**. The agent is equipped with tools such as adding code cells, inserting markdown cells, executing code, enabling it to modify the notebook comprehensively based on user instructions or by reacting to the Jupyter notebook events.
  225. This Agent is **innovative** as it is designed to **operate on the entire Notebook**, not just at the cell level, enabling more comprehensive and seamless modifications.
  226. The Agent can also run separately from the Jupyter server as the communication is achieved through RTC via the [Jupyter NbModel Client](https://github.com/datalayer/jupyter-nbmodel-client) and the [Jupyter Kernel Client](https://github.com/datalayer/jupyter-kernel-client).
  227. ```
  228. Jupyter AI Agents <---> JupyterLab
  229. |
  230. | RTC (Real Time Collaboration)
  231. |
  232. Jupyter Clients
  233. ```
  234. </details>
  235. ## Contributing
  236. ### Development install
  237. ```bash
  238. # Clone the repo to your local environment
  239. # Change directory to the jupyter_ai_agents directory
  240. # Install package in development mode - will automatically enable
  241. # The server extension.
  242. pip install -e ".[test,lint,typing]"
  243. ```
  244. ### Running Tests
  245. Install dependencies:
  246. ```bash
  247. pip install -e ".[test]"
  248. ```
  249. To run the python tests, use:
  250. ```bash
  251. pytest
  252. ```
  253. ### Development uninstall
  254. ```bash
  255. pip uninstall jupyter_ai_agents
  256. ```
  257. ### Packaging the library
  258. See [RELEASE](RELEASE.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.