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

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

Quick Start

# Authenticate for default local use
fab auth login

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

# Start session + execute code
fntk notebook start-session --workspace-id <WS_ID> --artifact-id <ART_ID> --json
fntk code run --workspace-id <WS_ID> --artifact-id <ART_ID> --code "print('hello')" --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

CLI Commands

fntk help              # Human-readable overview
fntk help --json       # Machine-readable manifest (for agents)

Output Format

Most operational commands with --json return the following stable envelope. Help and skill inspection use their own payloads. For backward compatibility, notebook get-content --output-file <FILE> returns status/file and writes raw notebook JSON to the file; notebook put-content --json returns status/message. Without --output-file, notebook get-content --json uses the normal envelope with notebook JSON in data.

Content downloads retain the original notebook JSON. Uploads and cell edits preserve attachments, saved output fields, and unrecognized JSON properties; cell source strings are serialized as line lists for the Notebook service. Content-only edits retain the cell type. An explicit batch cell_type conversion to code omits attachments from that cell, matching the Fabric editor's behavior. This does not restore fields already missing from an older export or save.

{
  "status": "success",
  "stage": "completed",
  "progress": 1.0,
  "message": "Found 14 notebooks",
  "data": { ... },
  "next_actions": [
    {
      "type": "once",
      "command": "fntk notebook start-session --workspace-id <WS> --artifact-id <ART> --json",
      "description": "Start a session on a notebook"
    }
  ],
  "plan_hints": ["Start a session", "Execute code"],
  "logs": [],
  "context": {"workspace_id": "..."},
  "error": null,
  "trace_id": "fntk-a1b2c3d4e5f6",
  "elapsed_ms": 234
}

next_actions Types

Feature Flags

Config file: ~/.fntk/config.json

Auth

fab auth login
fntk discover whoami --json

FNTK uses your current Fabric CLI login. After signing out or switching accounts, subsequent commands use the updated authentication state.

To obtain an MWC token, FNTK first asks Azure CLI for a Microsoft Entra ID (AAD) access token for the Power BI audience, https://analysis.windows.net/powerbi/api. FNTK verifies the token's signature, audience, and match to the current Fabric CLI tenant and account, then uses it for cluster discovery and generatemwctoken. If Azure CLI cannot supply a valid token for that account, FNTK falls back to FabAuth. The initial Fabric-audience token still comes from FabAuth. A Fabric CLI logout or an observed account change stops the operation, even if Azure CLI has a token.

External integrations can supply --token <AAD_TOKEN> or the daemon's X-FNTK-AAD-Token header. An invalid supplied token fails without switching to the local account, and a supplied token cannot borrow an additional audience from either local CLI.

Local Daemon (optional)

For long-running WebSocket connections and async execution:

fntk server start --json     # Start daemon on 127.0.0.1:19876
fntk server status --json    # Check status
fntk server stop --json      # Stop daemon

The daemon uses per-user auth nonce (~/.fntk/server.<port>.auth), bound to localhost only. Request tokens are forwarded on every session/code call. If a request token is supplied, it is authoritative: invalid or external tokens never fall back to the daemon's local identity. Managed sessions are bound to the authenticated principal; a mismatch closes the local WebSocket and returns SESSION_CONTEXT_MISMATCH. If an upgraded CLI reports DAEMON_AUTH_UPGRADE_REQUIRED, stop and restart the daemon using the commands above. Disconnecting locally does not cancel remote Spark jobs.

Agent Skill Init

fntk init installs the bundled fabric-notebook-workflow skill and configures the external Fabric Skills plugin for selected agent hosts. The bundled workflow skill uses project scope under the current directory by default; pass --global to install it in the user's home directory.

Local Git repository discovery, Fabric workspace scanning, workspace lookup, and agent instruction generation are temporarily unavailable from fntk init. When the selected host already has the global fabric-skills plugin, init reports it as found and does not register a marketplace or run a plugin installation. If a selected host CLI cannot be found, init completes its other stages and reports an actionable Fabric Skills warning in both text and JSON output.

In an interactive run, init installs the bundled fabric-notebook-workflow skill first and lets you choose project or global scope. It then configures Fabric Skills for each selected host that does not already have it: Copilot and Codex offer global installation or skip; Claude Code offers project, global, or skip. Non-interactive runs preserve the default installation behavior.

# Install skills for GitHub Copilot CLI in the current project
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

# Refresh previously installed skills/plugins
fntk init --update-skills -y

Flags:

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

Upgrade flow: after installing a newer fntk, run fntk init --update-skills -y to refresh installed workflow skills and Fabric Skills plugins.

When isolated telemetry is enabled, each invocation emits one aggregate init.summary metric with selected agent types, skill/plugin outcomes, completed stage, and error code. It does not include project paths, prompt input, or free-form error messages.

Bundled skill content remains inspectable with fntk skill list and fntk skill get <skill-id>.

For AI Agents

Agents can discover all capabilities via:

fntk help --json    # Returns full manifest: domains, commands, workflows, schemas

The manifest includes state machine definitions, output schema, and recommended workflows. See AGENTS.md for detailed agent integration guide.

Client attribution for integrations

Agent hosts should attach self-asserted caller metadata to each top-level FNTK invocation. fntk init generates the appropriate canonical client name for GitHub Copilot CLI, Claude Code, and Codex; terminal users do not configure it.

fntk code run ... --client-name github-copilot-cli --client-version 1.0.0

Operational commands accept --client-name, optional --client-version, --invocation-id UUIDv4, and --client-attribution {auto,explicit-only,off} at either the root or leaf position.

MCP hosts may declare connection metadata through initialize.params.clientInfo. A tools/call may override it using params._meta keys io.microsoft.fntk/client-name, io.microsoft.fntk/client-version, and io.microsoft.fntk/invocation-id.

Attribution is self-asserted telemetry metadata. Names are normalized to a fixed low-cardinality set, versions are bounded, and localhost caller headers are not forwarded to Fabric or WebSocket services. Disable attribution for one invocation with --client-attribution off.

Isolated telemetry (default)

Telemetry defaults to isolated when FNTK_TELEMETRY_RUNTIME is unset. CLI and daemon startup enable local file persistence and authorized remote telemetry through a private, low-priority worker process; no opt-in is required. Remote sending still requires a valid, unexpired notebook route and its existing identity/egress authorization. Unbound startup records remain local-only. Set FNTK_TELEMETRY_RUNTIME=off before starting FNTK to disable both telemetry sinks, not console output or CLI JSON responses. Empty or unknown explicit runtime values also disable both sinks. FNTK_TELEMETRY_DISABLED=1 disables only remote telemetry, leaving local persistence enabled in isolated mode.

Capture never synchronously falls back to HTTP, authentication, file writes, or waiting for a telemetry queue. Full/busy mailboxes reject the current event. The worker is not the Notebook daemon and does not restart or replay data after failure. Local logs and metrics are best-effort and eventually consistent. Explicit process shutdown has one total three-second telemetry budget. Default collection is not a claim of zero overhead or completed performance and cross-platform validation.

Embedded callers must call notebook_cli.telemetry.initialize_runtime() before constructing clients and shutdown_runtime() on exit. Preserve the original route handle with telemetry.operation_scope(handle) across threads or asynchronous operations; caller attribution is not authorization.

Use fntk telemetry status --json to inspect the running Notebook daemon's cached telemetry snapshot without starting a daemon. If unavailable, it reports only the current CLI runtime's status. Check snapshot age and unknown outcomes rather than treating missing telemetry as zero failures.