deepagent-lab 0.1.4

JupyterLab extension with chat interface for DeepAgents

Bring LangChain agents into your JupyterLab workflow

---

• Source code: github.com/dkedar7/deepagent-lab
• Installation: pip install -U deepagent-lab

---

A JupyterLab extension to allow your LangChain agents access to JuputerLab notebooks and files, enabling natural language interactions with your data science projects directly from JupyterLab.

Features

• Chat Interface: Sidebar for natural conversations with your agent
• Notebook Manipulation: Built-in tools for creating, editing, and executing Jupyter notebooks
• Human-in-the-Loop: Review and approve agent actions before execution
• Context Awareness: Automatically sends workspace and file context to your agent
• Custom Agents: Use your own langgraph-compatible agents seamlessly
• Auto-Configuration: Zero-config setup with automatic Jupyter server detection

Installation

pip install deepagent-lab

Quick Start

Recommended: Using the Launcher (Zero Configuration)

Instead of jupyter lab, use deepagent-lab command for automatic setup.

The easiest way to get started is using the deepagent-lab launcher command, which automatically configures everything for you:

# Set your API key (if using the default agent)
export ANTHROPIC_API_KEY=your-api-key-here

# Start JupyterLab with auto-configuration
deepagent-lab

That's it! The launcher will:

• Auto-detect an available port (starting from 8888)
• Generate a secure authentication token
• Set the required environment variables
• Launch JupyterLab with the proper configuration

Using custom arguments:

# All jupyter lab arguments are supported
deepagent-lab --no-browser
deepagent-lab --port 8889

Alternative: Manual Configuration

If you prefer manual control or need to use jupyter lab directly, you can set the environment variables yourself:

1. Configure environment variables (create a .env file or export):

# Required: Jupyter server configuration
export DEEPAGENT_JUPYTER_SERVER_URL=http://localhost:8888
export DEEPAGENT_JUPYTER_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")

# If using the default agent, set your API key
export ANTHROPIC_API_KEY=your-api-key-here

2. Start JupyterLab with matching configuration:

jupyter lab --port 8888 --IdentityProvider.token=$DEEPAGENT_JUPYTER_TOKEN

Important: The server URL and token must match between your environment variables and JupyterLab's startup parameters.

Using Custom Agents

Deepagent-lab is designed to work with any langgraph-compatible agent. You can easily use your own langgraph-compatible agents instead of the default agent.

Creating a Custom Agent

Create a file with your agent (e.g., my_agent.py):

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver
import os

# The agent automatically discovers the workspace
workspace = os.getenv('DEEPAGENT_WORKSPACE_ROOT', '.')

# Create your custom agent
agent = create_deep_agent(
    name="my-custom-agent",  # Optional: name shown in chat interface
    model="anthropic:claude-sonnet-4-20250514",
    backend=FilesystemBackend(root_dir=workspace, virtual_mode=True),
    checkpointer=MemorySaver(),
    tools=[...your_custom_tools...]
)

Configuring the Extension to Use Your Agent

Set the DEEPAGENT_AGENT_SPEC environment variable to point to your agent:

# Format: path/to/file.py:variable_name
export DEEPAGENT_AGENT_SPEC=./my_agent.py:agent

Then launch as normal:

# With the launcher (recommended)
deepagent-lab

# Or manually
jupyter lab --port 8888 --IdentityProvider.token=$DEEPAGENT_JUPYTER_TOKEN

The chat interface will automatically display your custom agent's name (if you set the name attribute).

Agent Portability

Agents configured for deepagent-lab work seamlessly with deepagent-dash:

# Same configuration works for both tools!
export DEEPAGENT_AGENT_SPEC=./my_agent.py:agent
export DEEPAGENT_WORKSPACE_ROOT=/path/to/project

# Run in JupyterLab
deepagent-lab

# Or run in Dash
deepagent-dash run

All environment variables use the DEEPAGENT_ prefix for compatibility.

Environment Variables

All configuration uses the DEEPAGENT_ prefix:

Variable	Purpose	Default	When to Set
DEEPAGENT_AGENT_SPEC	Custom agent location (path:variable)	Uses default agent	Optional: for custom agents
DEEPAGENT_WORKSPACE_ROOT	Working directory for agent	JupyterLab root	Optional
DEEPAGENT_JUPYTER_SERVER_URL	Jupyter server URL	Auto-detected	Manual config only
DEEPAGENT_JUPYTER_TOKEN	Jupyter auth token	Auto-generated	Manual config only
ANTHROPIC_API_KEY	Anthropic API key	None	Required for default agent

When using the deepagent-lab launcher, DEEPAGENT_JUPYTER_SERVER_URL and DEEPAGENT_JUPYTER_TOKEN are automatically configured and don't need to be set.

See .env.example for a complete configuration template.

Interface Controls

• ⟳ Reload: Reload your agent without restarting JupyterLab (useful during agent development)
• Clear: Start a new conversation thread
• Status Indicator:
  • 🟢 Green: Agent ready
  • 🟠 Orange: Agent loading
  • 🔴 Red: Agent error

Development

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.