Fabric Notebook Toolkit (fntk)

Agent Runtime Interface for Microsoft Fabric Notebooks — session management, code execution, Spark monitoring, all via CLI with structured JSON output.

Install

Requires Python 3.10-3.13 and access to a Fabric workspace with an active Spark-capable capacity.

# Install the public alpha release
pip install fabric-notebook-toolkit

Quick Start

# Sign in to both Fabric CLI and Azure CLI with the same account and tenant.
# Azure CLI must be installed before running az login.
fab auth login --tenant <TENANT_ID>
az login --tenant <TENANT_ID>

# Discover resources
fntk discover whoami --json
fntk discover list-workspaces --json
fntk discover list-notebooks --workspace-id <WS_ID> --json

# Start a session. Use data.session_id as <SID>.
fntk notebook start-session --workspace-id <WS_ID> --artifact-id <ART_ID> --json

# Repeat until data.livy_session_state is "idle".
fntk notebook get-session --workspace-id <WS_ID> --artifact-id <ART_ID> --session-id <SID> --json

# Submit code, then use the execution ID in the returned polling command as <EID>.
fntk code run --workspace-id <WS_ID> --artifact-id <ART_ID> --code "print('hello')" --json

# Repeat until data.status is "completed" or "error"; inspect data.outputs/data.error.
fntk code get-result --workspace-id <WS_ID> --artifact-id <ART_ID> --execution-id <EID> --json

# Monitor Spark
fntk monitor list-apps --workspace-id <WS_ID> --artifact-id <ART_ID> --livy-id <LID> --json
fntk monitor get-diagnostic --workspace-id <WS_ID> --artifact-id <ART_ID> --app-id <APP> --json

# Download logs
fntk logs get-driver --workspace-id <WS_ID> --artifact-id <ART_ID> --livy-id <LID> --app-id <APP> --json

Session startup can take several minutes. Follow next_actions for polling intervals and retry limits; stop on query errors, terminal failures, or timeout. Use get-session for the Livy session ID (<LID>) and list-apps for the Spark application ID (<APP>).

CLI Commands

fntk help              # Human-readable overview
fntk help --json       # Supported public commands, workflows and schemas

Use fntk <domain> --help for commands and options.

Output Format

Most operational commands with --json return this envelope. Example session query:

{
  "status": "success",
  "stage": "completed",
  "progress": 1.0,
  "message": "Session is idle",
  "data": {
    "session_id": "<SID>",
    "livy_session_state": "idle"
  },
  "next_actions": [],
  "plan_hints": [],
  "logs": [],
  "context": {"workspace_id": "<WS_ID>"},
  "error": null,
  "trace_id": "fntk-a1b2c3d4e5f6",
  "elapsed_ms": 234
}

Help and skill inspection use their own payloads. notebook get-content --output-file <FILE> returns status/file and saves raw notebook JSON; notebook put-content --json returns status/message. Ordinary notebook get-content --json places notebook JSON in data.

Content-only edits retain cell types, attachments and existing metadata. Explicit conversion to code removes that cell's attachments.

next_actions Types

Query success versus execution success

For notebook get-session and code get-result, top-level status: "success" means the query succeeded, not that Spark is ready or the code succeeded.

Exit code 0 alone does not guarantee successful Spark execution. Scripts and agents must inspect the nested state.

Runtime settings

Set environment variables before starting the CLI or daemon:

Auth

FNTK uses your current Fabric CLI identity. For notebook operations, install Azure CLI and sign in to both CLIs with the same account and tenant, as shown in Quick Start. An existing valid Azure CLI session can be reused. The --tenant option selects a directory; omit it from both commands only if both CLIs already use the intended tenant.

These are separate login flows, so first-time setup may require two interactive sign-ins. FNTK attempts a Fabric CLI fallback when Azure CLI cannot provide the additional token, but that fallback is not guaranteed. FNTK itself does not open a login prompt. Use fntk discover whoami --json to check your identity; this does not verify every permission needed for notebook operations.

Local Daemon

notebook start-session automatically starts a local daemon for persistent connections and asynchronous execution. Manual lifecycle management is optional:

fntk server start --json     # Start daemon on localhost (default port: 19876)
fntk server status --json    # Check status
fntk server stop --json      # Stop daemon

The daemon listens only on localhost. If an upgrade reports DAEMON_AUTH_UPGRADE_REQUIRED, stop and restart it. Stopping the local daemon does not cancel remote Spark jobs.

Agent Skill Init

fntk init installs the bundled workflow skill and configures the external Fabric Skills plugin for GitHub Copilot CLI (default), Codex or Claude Code. The bundled skill is project-local by default; --global installs it in your home directory. Interactive runs let you choose scope and skip plugin installation; -y or JSON output skips prompts and uses defaults.

# Set up GitHub Copilot CLI
fntk init

# Non-interactive JSON mode with all enabled agent targets
fntk init --agent copilot codex claude -y --json

# Install the bundled workflow skill globally
fntk init --global -y

# After upgrading FNTK, refresh installed skills/plugins
fntk init --update-skills -y

Use --skip-fabric-skills to skip the external plugin, or fntk init --help for all options. If a host CLI is unavailable, init reports a warning and completes the other setup steps.

Interactive terminal output uses color for headings, success, warnings, and errors. Set NO_COLOR=1 (or use redirected/JSON output) for plain text.

For AI Agents

The JSON manifest describes supported public commands, workflows, output schemas and state transitions. Built-in guidance is available without a repository checkout:

fntk skill list --json
fntk skill get pyspark --json

Integrations can identify the calling host with --client-name github-copilot-cli, --client-name claude-code or --client-name codex. This is optional, self-asserted telemetry metadata, not authorization; terminal users do not need to configure it. Use --client-attribution off to disable attribution.

Telemetry

By default, FNTK records logs and metrics locally and sends authorized remote telemetry to Microsoft. Remote sending requires an authenticated notebook context; startup events without one remain local. Collection is best-effort.

Set these environment variables before starting the CLI or daemon:

Console output and CLI JSON remain available with either setting. fntk telemetry status --json reports the running daemon's cached status, or only the current CLI runtime if no daemon snapshot is available. It does not start a daemon; missing telemetry does not establish whether a Spark job succeeded.