Jupyter AI Documentation

Jupyter AI is an open-source extension for JupyterLab that integrates agentic AI into computational notebooks. It provides a native chat UI for collaborating with frontier AI agents (such as Claude, Gemini, Mistral Vibe, and others) via the Agent Client Protocol (ACP).

Key capabilities include:

• Agentic Actions: Agents can read/write files, run terminal commands, and interact with notebooks using a built-in Jupyter MCP server.
• Security: A permission system requires user approval before agents perform sensitive actions like writing files or executing commands.
• Context Management: Supports multiple concurrent chats and allows dragging and dropping files or notebook cells as context.
• Extensibility: Supports custom Model Context Protocol (MCP) servers and allows developers to register custom AI personas via an entry points API.

Contributors should adhere to these core principles to maintain user trust:

1. Vendor-agnostic: Do not discriminate between agent or model providers.
2. Explicit prompts only: Do not watch files or send prompts automatically; any file-watching must be opt-in.
3. Transparency: Chat prompts, system messages, and templates must be open source.
4. Traceability: Users must know when Jupyter AI has been used (e.g., via notebook metadata or explicit labels).
5. Human-centered design: Interfaces should feel like standard chat applications, and magic commands should behave like standard IPython magics.

Jupyter AI v3.1.0 introduces enhanced in-chat controls for a single active persona. These controls allow users to manage the following parameters directly from the chat input:

• model: Select the underlying model.
• effort: Adjust the effort level.
• context usage: Monitor and manage context usage.
• thinking: Access/view thinking blocks (via agent_thought_chunk events).
• cost: View the running cost total.

These settings are read from and written to the Agent Communication Protocol (ACP).

In version 3.2.0, the AI persona is deconstructed into five swappable, instance-level building blocks. This allows developers to change a persona's behavior, identity, or engine at runtime without recreating the persona instance.

The five building blocks are:

• Identity: Specifies the name and avatar shown in chat.
• Model: Specifies the model provider, model ID, and model URL.
• Context: Specifies skills paths, MCP servers, and the system prompt.
• Engine: The implementation layer (e.g., Claude, Codex) that processes messages.
• Options: Unstructured per-engine settings (e.g., hyperparameters, planning mode).

Future updates in the v3.1 roadmap include multi-persona support and improved session management:

• Multi-persona support: A roster UI to track multiple personas in a single chat, featuring lazy initialization (creating personas only when first used) and routing clarity.
• Session management: Capabilities to list, resume, delete, and gracefully close sessions, including agent-set chat titles.
• Enhanced UI: Slash-command autocomplete polish, execution-plan and task-list displays, mode selectors for compatible agents, and image pasting into the chat input.

In Jupyter AI 3.1, chats can contain multiple AI personas. The 'active persona' determines which model, effort level, and context usage controls are displayed in the chat input.

• Automatic Activation: The active persona is automatically updated when you @-mention a persona in a message. Once mentioned, that persona remains active for subsequent messages until another persona is mentioned or manually selected.
• Manual Selection: You can switch the active persona directly using the selector in the chat input area. This allows you to change which persona you are addressing without retyping the @ symbol.
• Single Persona Chats: If a chat contains only one persona, it is always the active persona by default.

End-to-end (E2E) tests use Playwright and Galata.

1. Initial Setup (once per submodule):

source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm install
jlpm playwright install

2. Handle Snapshots: If you are not on Linux, you must generate local snapshots before running tests for the first time:

source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm test:update

3. Execute Tests:

source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm test

# Update snapshots (non-Linux users only)
source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm test:update

# Run tests
source .venv/bin/activate
cd <submodule>/ui-tests/
jlpm test

Jupyter AI provides %%ai (cell magic) and %ai (line magic). Models are identified by a global model ID using the syntax <provider-id>/<local-model-id>.

To use a persona (agent) instead of a model, specify the persona name instead of the model ID (ensure the persona is installed and active).

%%ai bedrock/anthropic.claude-3-5-haiku-20241022-v1:0
What is the capital of France?

Jupyter AI automatically detects available agents in your environment.

1. Start JupyterLab: jupyter lab.
2. Create a new chat by clicking the Chat card in the launcher page or the + button in the chat sidebar panel.

Note: Chats are stored as files in your workspace. You can resume existing chats by re-opening them or manage multiple simultaneous chat threads.

Jupyter AI does not ship with agents by default. You must install agents following their official documentation. Some agents require an additional Agent Client Protocol (ACP) adapter package to work within Jupyter AI.

Required ACP Adapters

• Claude Code: npm install -g @agentclientprotocol/claude-agent-acp
• Codex: npm install -g @zed-industries/codex-acp
• Mistral Vibe: uv tool install mistral-vibe or pip install mistral-vibe

Use curly brace {} syntax to include Python variables, cell inputs, outputs, or errors in your prompt.

• {variable_name}: Interpolates a Python variable.
• {In[n]}: Interpolates the input of cell n.
• {Out[n]}: Interpolates the output of cell n.
• {Err[n]}: Interpolates the error from cell n.

Shortcut for fixing errors: Use %ai fix <model_id> to automatically explain and attempt to fix the most recent error.

# Using a variable
poet = "Walt Whitman"
%%ai chatgpt
Write a poem in the style of {poet}

# Using cell history
%%ai cohere:command-xlarge-nightly
Please explain the code below:
--
{In[11]}

# Fixing an error
%ai fix anthropic:claude-v1.2