Notebook Quick Start

This is the thinnest AGILab onboarding path for Python users who prefer a notebook over the web UI. It uses agi-core directly through AgiEnv and AGI.run(...) and keeps the first run local.

Use this page when you want a first successful run with less UI surface area and want to stay in a notebook while learning the runtime. It is a supported local-first onboarding path for newcomers who prefer code over UI.

When this path helps

  • You already work comfortably in Jupyter.

  • You want to understand the runtime from code first.

  • You want a smaller mental model before learning PROJECT, ORCHESTRATE, PIPELINE, and ANALYSIS.

What this path does not cover

  • App selection through the AGILab sidebar.

  • Generated snippets from ORCHESTRATE.

  • Pipeline editing in the UI.

  • Cluster or service-mode operations.

You can stay in notebook mode for your first local runs. Move to the web UI later when you want the higher-level AGILAB workflow around the same API.

Repository launch flow

From the AGILab repository root:

git clone https://github.com/ThalesGroup/agilab.git
cd agilab
./install.sh --install-apps --test-apps
uv run --with jupyterlab jupyter lab examples/notebook_quickstart/agi_core_first_run.ipynb

The notebook file lives in the repository at examples/notebook_quickstart/agi_core_first_run.ipynb.

Minimal notebook cells

Cell 1: resolve the repository and built-in apps path.

from pathlib import Path

def find_repo_root(start: Path) -> Path:
    for candidate in (start, *start.parents):
        if (candidate / "pyproject.toml").is_file() and (candidate / "src/agilab/apps/builtin").is_dir():
            return candidate
    raise RuntimeError(
        "Launch this notebook from inside the AGILab repository, or edit REPO_ROOT manually."
    )

REPO_ROOT = find_repo_root(Path.cwd().resolve())
APPS_PATH = REPO_ROOT / "src/agilab/apps/builtin"
APP = "mycode_project"

Cell 2: build AgiEnv and run the smallest local AGI.run(...) shape.

from agi_cluster.agi_distributor import AGI
from agi_env import AgiEnv

app_env = AgiEnv(apps_path=APPS_PATH, app=APP, verbose=1)
result = await AGI.run(
    app_env,
    scheduler="127.0.0.1",
    workers={"127.0.0.1": 1},
    mode=0,  # plain local Python execution
)
result

Cell 3: inspect the run artifacts.

log_root = Path.home() / "log" / "execute" / "mycode"
print(log_root)

How this maps back to the GUI

  • Notebook AgiEnv(apps_path=..., app="mycode_project") corresponds to choosing a project in PROJECT.

  • Notebook AGI.run(...) corresponds to the generated snippet from ORCHESTRATE.

  • The output path under ~/log/execute/mycode is the same family of artifacts the UI writes and reuses.

  • You only need to move to PIPELINE when you want saved, repeatable steps instead of ad hoc cells.

Optional next step

After one successful notebook run, you can keep working in notebooks or move to the UI:

  1. Open the AGILab web UI.

  2. Select the same mycode_project app.

  3. Recreate the run in ORCHESTRATE if you want to learn the UI vocabulary.