jupyter-ai-quickagent

A Jupyter AI persona that implements LangChain Deep Agents with an interactive agent configuration flow. This can be added as a submodule for jupyter-ai in jupyter-ai-contrib. Also provided is a one shot interactive installer that installs the contributor version of jupyter-ai and all CLIs from major providers.

Features

This is an early attempt at building a Persona that can create a collection of personal agents for re-use.

• Interactive agent builder — step-by-step setup via chat (name, purpose, tools, search, skill files)
• Shared LLM authentication — automatically uses the model and credentials configured in Jupyter AI's Settings > AI Settings (via LiteLLM), so there is no separate API key setup
• Persistent agents — saved to disk and reusable across sessions
• Built-in tools — file I/O, shell execution, Python REPL, planning (provided by the Deep Agents framework)
• Search integration — DuckDuckGo (built-in, no API key), plus optional Tavily, Wikipedia, arXiv, PubMed
• Skills directory — point to a folder of .md files with specialized instructions, domain knowledge, or workflows (same as Claude's --add-dir)
• Chat commands — @QuickAgent create, @QuickAgent list, @QuickAgent use <name>, etc.

Prerequisites

• Jupyternaut (jupyter_ai_jupyternaut) must be installed and a chat model must be configured in Settings > AI Settings. QuickAgent reuses this model — no environment-variable API keys are needed for the LLM itself.
• Python >= 3.11

Quick Installation with Jupyter AI

Install uv first.

Then, you can just run the install script. This will install all the necessary dependencies and set up the environment for you. To do this download the install_nondev.sh script and run it in your terminal:

chmod a+x install_nondev.sh
./install_nondev.sh 

This will install everything and also start Jupyter Lab. For later sessions, you will need to start as follows:

cd jupyter-ai-quickagents
source .venv/bin/activate
jupyter lab

If you are going to use any of the CLI coding agents (e.g., Claude Code, Gemini CLI, Codex CLI, Kiro CLI, OpenCode CLI, etc.) with Jupyter AI then also download and run the install_cli.sh script.

chmod a+x install_cli.sh
./install_cli.sh

Developer Installation

Install just and uv first.

For developers, it is easiest to install this package with Jupyter AI one-shot. You will be prompted to install the quickagent repo. However, if you do not want the developer install, i.e., just the user install, then just use the script above.

In order to install jupyter-ai using all the submodules in jupyter-ai-contrib you can use the installer provided in this repository, see install.sh. To use it:

chmod a+x install.sh
./install.sh

Installing only the CLI version

Use these steps if you do not want to install the full JupyterLab/Jupyter AI integration and only want to use the CLI interface. You can do this in any conda, mamba, micromamba, uv, python virtual environment or just in your base environment. For example, to create a uv environment, the steps are shown below.

Clone the repo and install requirements:

git clone https://github.com/srdas/jupyter-ai-quickagent.git
cd jupyter-ai-quickagent

Create the virtual environment:

uv venv --python 3.12
source .venv/bin/activate
 # On Windows: .venv\Scripts\activate

Install dependencies:

uv pip install -r CLI-requirements.txt 
# you can drop `uv` if you are not using it

Check that it is working:

python -m jupyter_ai_quickagent

You should see the help menu.

Connect the QuickAgent to a model, for example:

export QUICKAGENT_MODEL='us.anthropic.claude-opus-4-6-v1'

To run it, start by creating a Quick Agent:

python -m jupyter_ai_quickagent create

It will ask you a series of questions, and then create your agent based on your answers. Make sure to save your agent.

To run the agent proceed with:

python -m jupyter_ai_quickagent run <Agent-Name> <prompt>

Some examples are shown below in Quick Start.

Quick Start

1. Ensure a chat model is configured in Settings > AI Settings (the same one Jupyternaut uses).
2. Start JupyterLab: just start (developer version) or jupyter lab (user version)
3. Open the Jupyter AI chat panel from the left sidebar.
4. Send @QuickAgent create to build your first agent.
5. Follow the five interactive prompts (name, purpose, tools, search tools, skill files).

See USAGE.md for the full walkthrough and command reference. You can see how QuickAgent appears as one of the Personas in the chat:

After setting up agents, you will see them in the chat:

Example 1

A mathematician colleague, Professor Dan Ostrov, wrote a short piece titled ``What Are Good Math Questions?'' and this is converted into a SKILL.md file stored anywhere on disk and referred to in the skill json file titled `mathq.json` shown later below. You can refer to the skill file to see the attributes of a good mathematical question that you want the `MathQ` agent to use.

Let's use the MathQ agent and have it generate a math question:

Here is the answer for the question it asked:

The agent will also tell you why this is a good question conforming to the attributes in the SKILL file.

Of course, whether this is a good math question eventually is a matter of taste and judgment, which AI agents are not presumed to have. Hopefully, the SKILL file provides enough guidance.

Example 2

This example sets up a QuickAgent called Researcher to generate an entire research paper in LaTeX. We undertake the following steps:

1. Go to kaggle and download the dataset from the page on Teen Mental Health. Drop it in its own folder, in this example titled mentalhealth.
2. Clone the repo: https://github.com/srdas/skill-collection.

git clone https://github.com/srdas/skill-collection.git

3. In the chat panel, run @QuickAgent create and the follow the steps to complete the creation of the quick agent. It will instantiate the agent, and you will see that it is ready for use. To see this, see the chat stream. You can use the same choices in the provided chat. Of course, for the question on skills, point to the <path-to-skill-collection>/researcher. The QuickAgent will use all the skills in this folder, as well as any supporting code.
4. Next, enter @QuickAgent use Researcher. And then simply say Analyze <path-to-mentalhealth-folder>. The agent will use all the files in the folder to complete the task and prepare the paper. As you can see from the chat stream, the process only takes ~10 minutes and produces a summary in the chat, detailed LaTeX file, PDF paper, and a notebook that reproduces the tables and figures. All generated code and supporting artifacts (tables and figures) are in the output folder.

How Authentication Works

QuickAgent does not manage its own API keys. Instead, it reads the model ID and credentials from Jupyternaut's ConfigManager, which is populated through the Settings > AI Settings UI. Under the hood this uses LiteLLM, so any provider supported there (OpenAI, Anthropic, Azure, Google, AWS Bedrock, etc.) works automatically.

Development

cd jupyter-ai-quickagent
just pytest     # run tests
just lint       # run linters

Updates to pyproject.toml

The installler install.sh will automatically update the pyproject.toml of the jupyter-ai-devrepo workspace in the following two places.

[project.optional-dependencies]
optional = [
    "jupyter_ai_litellm",
    "jupyter_ai_jupyternaut",
    "jupyter_ai_magic_commands",
    "jupyter_ai_quickagent",
]

[tool.uv.sources]
jupyter_ai = { workspace = true }
jupyter_server_documents = { workspace = true }
jupyterlab_chat = { workspace = true }
jupyter_ai_router = { workspace = true }
jupyter_ai_persona_manager = { workspace = true }
jupyter_ai_litellm = { workspace = true }
jupyter_ai_magic_commands = { workspace = true }
jupyter_ai_chat_commands = { workspace = true }
jupyterlab_commands_toolkit = { workspace = true }
jupyter_ai_jupyternaut = { workspace = true }
jupyter_ai_acp_client = { workspace = true }
jupyter_server_mcp = { workspace = true }
jupyter_ai_tools = { workspace = true }
jupyter_ai_quickagent = { workspace = true }

Using QuickAgent

Please refer to detailed usage instructions in USAGE.md.

How are agents stored?

Each agent is saved as a JSON file in ~/.jupyter/jupyter-ai/quickagents/. The filename is the lowercase agent name (e.g., mathq.json for the MathQ agent shown in the screenshot above). Here is an example:

{
  "name": "MathQ",
  "purpose": "Generate and solve math questions that test deep conceptual understanding rather than mechanical computation or memorized formulas.",
  "tools": [
    "execute", "read_file", "write_file", "edit_file",
    "ls", "glob", "grep", "python_repl", "web_fetch", "todo"
  ],
  "search_tools": [],
  "skills_dir": "/path/to/skill-collection/math_questions",
  "system_prompt": ""
}

The @QuickAgent list command reads this directory and displays all available agents, as shown in the image above. To remove an agent, simply delete its JSON file from the quickagents/ folder, or use the @QuickAgents delete <name of agent> prompt in the chat panel.

Some additional examples of agents are the Joker agent and the Researcher agent, shown below. First, joker.json:

{
  "name": "Joker",
  "purpose": "Agent that writes a standup comdey joke in a few sentences from the provided file or URL",
  "tools": [
    "execute",
    "read_file",
    "write_file",
    "edit_file",
    "ls",
    "glob",
    "grep",
    "python_repl",
    "web_fetch",
    "todo"
  ],
  "search_tools": [
    "duckduckgo_search"
  ],
  "skills_dir": "/Users/sanjivda/CODE/skill-collection/comedy_writer",
  "system_prompt": ""
}

And then, researcher.json:

{
  "name": "Researcher",
  "purpose": "Agent to read all files in a folder, formulate good research questions, perform empirical analysis, present results with visualizations, generate a reproducible Jupyter notebook, and produce a LaTeX paper",
  "tools": [
    "execute",
    "read_file",
    "write_file",
    "edit_file",
    "ls",
    "glob",
    "grep",
    "python_repl",
    "web_fetch",
    "todo"
  ],
  "search_tools": [],
  "skills_dir": "/Users/sanjivda/CODE/skill-collection/researcher",
  "system_prompt": ""
}