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
fab auth login

# Set environment (non-prod requires a verified @microsoft.com identity)
fntk env set msit          # msit | prod | daily | dxt | edog

# 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

All commands with --json return a stable envelope:

{
  "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

Environment Configuration

Priority (highest to lowest):

1. FNTK_ENV
2. Legacy FAB_API_ENDPOINT_FABRIC
3. ~/.fntk/env.json
4. Legacy ~/.fntk/config.json → default_env (migration compatibility)
5. Default: prod

fntk env                       # Same as env show
fntk env show --json           # Effective environment + identity-scoped available environments
fntk env set msit --json       # Persists strict, atomic ~/.fntk/env.json
fntk env reset --json          # Removes env.json + legacy default_env

Environment files and variables express only the requested environment. Non-production is effective only after the actual prod-Fabric-audience token is signature-verified and its normalized login domain is exactly microsoft.com. External users, unavailable identity, and invalid sources safely use effective prod. env show reports only prod in available_environments for external or unverified identities; verified internal users see prod, msit, daily, dxt, and edog. An invalid higher-priority source shadows all lower sources; FNTK never falls through to a stale non-prod file.

env set never modifies the parent shell. A process override can therefore remain effective after persistence; inspect process_override and next_actions. env reset is idempotent and does not clear process variables. To remove old user-level overrides:

# Windows PowerShell (current process + persisted user variables)
Remove-Item Env:FNTK_ENV -ErrorAction SilentlyContinue
Remove-Item Env:FAB_API_ENDPOINT_FABRIC -ErrorAction SilentlyContinue
[Environment]::SetEnvironmentVariable("FNTK_ENV", $null, "User")
[Environment]::SetEnvironmentVariable("FAB_API_ENDPOINT_FABRIC", $null, "User")

# POSIX shell (current process; also remove matching shell/profile exports)
unset FNTK_ENV FAB_API_ENDPOINT_FABRIC

During the compatibility window, a valid legacy config.json.default_env is migrated to env.json under a cross-process lock while the legacy key is retained for rollback.

Feature Flags

Config file: ~/.fntk/config.json Env var override: FNTK_<FLAG_NAME> (e.g. FNTK_LOG_LEVEL=debug)

Auth

fab auth login     # Preferred (Fabric CLI MSAL cache)
az login           # Fallback

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 environment and principal; a mismatch closes the local WebSocket and returns SESSION_CONTEXT_MISMATCH. Environment set/reset waits for a daemon revision acknowledgement and reports ENV_DAEMON_RELOAD_FAILED without rolling back the already-persisted file.

Repository Init

fntk init bootstraps agent workflows. In a git repository it installs the bundled fabric-notebook-toolkit skill, detects Fabric workspace folders from .platform files, resolves workspace/capacity IDs, and writes per-workspace agent instructions. Outside a git repository it installs skills only, defaulting to user-global scope. When .vscode/settings.json contains fabric.dataEngineering.gitWorkspaceBindings, its workspace IDs and capacity IDs are used directly before any Fabric workspace listing is requested. VS Code JSONC comments and trailing commas are supported. 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-toolkit 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.

Generated instruction targets use native agent mechanisms:

• GitHub Copilot CLI: .github/instructions/*.instructions.md
• Codex: workspace-local AGENTS.md
• Claude Code: workspace-local CLAUDE.md

# Initialize the current git repo
fntk init

# Only scan one subtree for Fabric workspaces
fntk init fabric/yilintest2

# Initialize one explicit workspace folder
fntk init --workspace-folder fabric/yilintest2

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

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

# Re-identify workspaces and refresh managed prompts
fntk init fabric/yilintest2 --update-workspaces -y

# Refresh both installed skills/plugins and workspace instructions
fntk init --update -y

Flags:

If an agent instruction file already exists, interactive runs ask before appending/updating the FNTK managed prompt block. Non-interactive runs skip existing files unless -y is set, and generated prompt content includes FNTK markers for future updates.

At the interactive workspace-name prompt, enter :i to ignore that workspace folder. Other input, including skip, is treated as a workspace name.

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 skills/plugins, then run fntk init [path] --update-workspaces -y to re-resolve workspaces and refresh managed prompt blocks.

Each invocation emits one aggregate init.summary metric, including the selected agent types, skill/instruction outcomes, completed stage, error code, and counts for detected, automatically resolved, user-renamed, explicitly ignored, and unresolved workspaces. The event does not include repository paths, workspace names or IDs, 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.