FabricFabricHarness
Examples

Runnable examples

Runnable commands, expected proof, failure behavior, and cleanup for every maintained Fabric Harness example.

This guide is synchronized with every top-level workspace under examples/. Use it after the complete framework learning path to choose a runnable proof for a feature. Commands assume an authorized source checkout from the repository root.

For a public project without source access, initialize a workspace with:

npx --yes @fabric-harness/cli@latest init

Then copy the public API pattern from the linked feature guide. An example build proves local composition; it does not establish readiness for a managed provider.

How to run a row

Run the first command as the deterministic or build proof. Run the second command, when present, for the workload or development server. pnpm --dir executes the script from the example's own workspace, so the commands work when copied from the repository root.

Framework foundations

Learn finite and persistent lifecycles, state, schemas, configuration, tools, approvals, tasks, schedules, application routes, and browser clients before adding a managed runtime.

  • Prerequisites and authentication: Node.js 22 or newer and the repository pnpm version. Use the mock commands where shown; model-backed commands additionally need the credential for the model configured by that workspace.
  • Expected evidence: The selected check exits successfully or the run returns the typed result, durable state transition, event, or browser behavior described in the proof column.
  • Failure behavior: Invalid input, policy denial, approval rejection, exhaustion, cancellation, timeout, and unknown capabilities remain distinct terminal outcomes. A mock path never establishes provider readiness.
  • Cleanup: Stop development servers with Ctrl-C. Retain local run records only when they are needed for logs or replay; remove example-local databases and artifacts when the proof is complete.
ExampleCommandWhat it proves
agent-registrypnpm --dir examples/agent-registry run check
pnpm --dir examples/agent-registry run run
This credential-free example validates a vertical-neutral agent definition, pins an immutable version and model budget, separates proposal authority from execution authority, and proves that an approval-required autonomy ceiling prevents direct execution.
application-routespnpm --dir examples/application-routes run check
pnpm --dir examples/application-routes run dev
Runs authenticated custom Fetch routes and middleware, including a report route and durable delivery to an addressable customer agent.
database-persistencepnpm --dir examples/database-persistence run check
pnpm --dir examples/database-persistence run dev
Uses one persistence contract for sessions, submissions, conversation offsets, attachments, finite runs, budgets, and cascade deletion across local libSQL and optional managed databases.
dynamic-agentpnpm --dir examples/dynamic-agent run build
pnpm --dir examples/dynamic-agent run dev
This example composes a persistent agent with hooks. It stores milestone state durably, unlocks advanced_analysis after the first milestone, upgrades its model after the second, streams a named data-progress part, attaches response metadata, and uses an agent-finish guard to keep the same response working until complete_milestone runs.
finite-jobspnpm --dir examples/finite-jobs run check
pnpm --dir examples/finite-jobs run dev
Runs a typed parent job, admits an idempotent child run through middleware, and exposes the child receipt and event stream through the public run protocol.
hello-worldpnpm --dir examples/hello-world run buildDefines the functionally named hello and ask finite agents, then proves config defaults, credential-free mock execution, and optional durable Temporal execution.
minimalpnpm --dir examples/minimal run buildThe smallest possible Fabric Harness agent. No input schema, no output schema, no capability policy, no session store, no artifacts. Just defineAgent({...}) + session.prompt against a model of your choice.
react-chatpnpm --dir examples/react-chat run check
pnpm --dir examples/react-chat run dev
Connects a React client to the public Harness protocol, streams transient SSE updates, reconciles them with durable messages, and exercises responsive light and dark layouts.
scheduled-jobspnpm --dir examples/scheduled-jobs run check
pnpm --dir examples/scheduled-jobs run dev
Declares a weekday report schedule and demonstrates local Node execution plus Cloudflare Cron generation, tenant-aware admission, and public run inspection.
with-approvalpnpm --dir examples/with-approval run buildDemonstrates policy-gated tool execution.
with-checkpointpnpm --dir examples/with-checkpoint run build
pnpm --dir examples/with-checkpoint run run
The workspace-recovery finite agent proves that a local sandbox can return to a named checkpoint. It writes one file, takes a checkpoint, writes a second file, restores the checkpoint, and reports the recovered filesystem state.
with-configpnpm --dir examples/with-config run build
pnpm --dir examples/with-config run run
Demonstrates central workspace configuration through .fabricharness/config.ts.
with-finish-toolpnpm --dir examples/with-finish-tool run build
pnpm --dir examples/with-finish-tool run run
Demonstrates the finish / give_up result tool pattern for structured output.
with-packaged-skillspnpm --dir examples/with-packaged-skills run build
pnpm --dir examples/with-packaged-skills run run
Demonstrates packaged skills with lazy resource loading.
with-signal-messagespnpm --dir examples/with-signal-messages run build
pnpm --dir examples/with-signal-messages run run
Demonstrates session.createSignalEntry() for injecting typed signal entries into the session history.
with-skillpnpm --dir examples/with-skill run build
pnpm --dir examples/with-skill run run
The personalized-greeter finite agent loads a Markdown-first hello-skill and the friendly role from the embedded .fabricharness/ workspace, then invokes the skill with typed arguments.
with-taskpnpm --dir examples/with-task run build
pnpm --dir examples/with-task run run
Demonstrates parent/child task orchestration with shared durable session storage.
with-toolspnpm --dir examples/with-tools run build
pnpm --dir examples/with-tools run run
Demonstrates built-in sandbox file tools with durable session history.

Runtimes, sandboxes, sources, and stores

Move the same public lifecycle across local, container, remote-sandbox, durable workflow, object-source, and database boundaries.

  • Prerequisites and authentication: Start with the local or Docker proof. Provider-backed workspaces require the provider credential, target account, supported region or plan, and any runtime-specific CLI named in its guide.
  • Expected evidence: A build proves adapter composition. A live run must additionally prove capability discovery, bounded command or file behavior, cancellation, and resource reclamation on the selected backend.
  • Failure behavior: Missing credentials, unsupported operations, isolation escape attempts, network denial, process failure, timeout, cancellation, and cleanup failure surface explicitly; Harness does not redirect work to the host or another backend.
  • Cleanup: Every live sandbox or deployment must stop its exact remote resource. Source mounts are read-only and detach with the session; durable stores retain only the records selected by the example retention policy.
ExampleCommandWhat it proves
coding-agent-litepnpm --dir examples/coding-agent-lite run buildClones a repo into a Docker sandbox, installs dependencies, then runs an arbitrary prompt against the cloned source. This demonstrates Fabric Harness lite mode for coding-agent workflows in about 13 lines.
remote-coding-agentpnpm --dir examples/remote-coding-agent run buildProvider-neutral remote sandbox example for coding agents.
with-azurepnpm --dir examples/with-azure run build
pnpm --dir examples/with-azure run build:foundry
Minimal Fabric Harness agent that runs through an Azure OpenAI deployment with Azure Key Vault-resolved secrets.
with-cloudflare-sandboxpnpm --dir examples/with-cloudflare-sandbox run build
pnpm --dir examples/with-cloudflare-sandbox run build:cloudflare
Builds a Cloudflare Worker artifact that uses Cloudflare Sandbox containers for shell and filesystem operations. It includes a finite job and a persistent agent backed by Durable Object admission, FIFO leases, offset streams, attachment storage, abort, reconciliation, and cascade deletion.
with-cloudflare-shell-workspacepnpm --dir examples/with-cloudflare-shell-workspace run build
pnpm --dir examples/with-cloudflare-shell-workspace run build:cloudflare
This example targets Cloudflare Workers with the early-preview @cloudflare/computer Workspace backend.
with-cloudflare-workers-aipnpm --dir examples/with-cloudflare-workers-ai run build
pnpm --dir examples/with-cloudflare-workers-ai run dev
Builds and optionally deploys a Cloudflare Worker that resolves Workers AI through its native binding without an API key in agent state.
with-daytonapnpm --dir examples/with-daytona run buildRuns a bounded shell workload in a Daytona-managed remote development sandbox.
with-dockerpnpm --dir examples/with-docker run buildRuns standard Harness file and shell tools inside a Docker container with a scoped workspace mount.
with-e2bpnpm --dir examples/with-e2b run buildRuns a finite job in E2B, streams bounded command output, and removes the sandbox during session cleanup.
with-kubernetespnpm --dir examples/with-kubernetes run build
pnpm --dir examples/with-kubernetes run run
The kubernetes-system-inspector finite agent attaches a Harness sandbox to an existing Kubernetes pod and runs a bounded diagnostic command in /workspace.
with-local-shellpnpm --dir examples/with-local-shell run build
pnpm --dir examples/with-local-shell run run
The node-version-inspector finite agent uses the local sandbox and session.shell() to report the Node.js version available to a Harness workload.
with-modalpnpm --dir examples/with-modal run buildRuns a finite Harness workload in a Modal serverless sandbox through the portable sandbox contract.
with-postgres-storepnpm --dir examples/with-postgres-store run build
pnpm --dir examples/with-postgres-store run run
Demonstrates configuring one Postgres bundle for sessions, submissions, conversation streams, attachments, finite runs, and cost budgets.
with-s3-sourcepnpm --dir examples/with-s3-source run build
pnpm --dir examples/with-s3-source run run
The s3-report-browser finite agent mounts a bounded S3 prefix as a read-only Harness source and lists its files with the built-in glob tool. It needs no embeddings, retrieval service, or vector database.
with-temporalpnpm --dir examples/with-temporal run build
pnpm --dir examples/with-temporal run run:mock
Runs the temporal-agent through a real Temporal worker with deterministic workflow boundaries, plus a credential-free Node-target mock path for local verification.
with-vercel-sandboxpnpm --dir examples/with-vercel-sandbox run buildRuns a finite job through Vercel Sandbox, forwards timeout cancellation, and stops the sandbox during cleanup.

Delivery, security, and operations

Prove authenticated ingress, channel identity, private networking, redacted telemetry, evaluations, and operational objectives around the agent lifecycle.

  • Prerequisites and authentication: The deterministic checks need only Node.js and pnpm. Live channel and voice paths require their signing secrets, provider credentials, callback URLs, and a store suitable for duplicate-delivery and restart tests.
  • Expected evidence: Evidence includes verified ingress identity, governed replies, redacted correlation fields, evaluated SLO decisions, or an allowed network path paired with a denied bypass.
  • Failure behavior: Bad signatures, stale timestamps, duplicate delivery, tenant mismatch, redaction violations, unavailable exporters, and disallowed network destinations fail closed or enter the documented retry path.
  • Cleanup: Stop local listeners, remove temporary provider callbacks and test subscriptions, revoke short-lived credentials, and retain only redacted operational evidence required by policy.
ExampleCommandWhat it proves
operational-slospnpm --dir examples/operational-slos run testExports stable Harness operational metrics, evaluates the reference SLO policy, and validates importable Prometheus and Grafana assets.
private-networkingpnpm --dir examples/private-networking run test
pnpm --dir examples/private-networking run start
Proves that an allowed request succeeds through the configured proxy while a direct network bypass fails.
voice-data-collectorpnpm --dir examples/voice-data-collector run buildUses OpenAI Realtime to collect functionally named fields, submits typed submit_field calls, and persists the resulting field map in session memory.
with-channel-adapterspnpm --dir examples/with-channel-adapters run check
pnpm --dir examples/with-channel-adapters run dev
This runnable workspace mounts all 18 first-party channel adapters on one persistent agent.
with-observabilitypnpm --dir examples/with-observability run testThis example emits the same redacted Fabric observability record to Braintrust, Jetty, and Sentry adapter callbacks, with stable job, agent, session, submission, and tenant correlation. The observability.eval.ts fixture runs through @fabric-harness/evals and Vitest. OpenTelemetry's hierarchical span adapter is covered by packages/sdk/test/otel-observer.test.ts and accepts the same correlation fields.
with-slack-channelpnpm --dir examples/with-slack-channel run build
pnpm --dir examples/with-slack-channel run dev
An end-to-end channel example: a Slack app mention drives a persistent agent, which replies in the same thread. Demonstrates the channels workstream (design) — webhook ingress → dispatch → outbound tool, with exactly-once delivery and per-user identity.

End-to-end workload examples

Apply the framework to recognizable engineering and support work without treating the workload prompt as a substitute for lifecycle, policy, and cleanup controls.

  • Prerequisites and authentication: Most workloads require the model credential declared by the example. Shell or repository workloads also need their named local tools, fixtures, and read or write permissions.
  • Expected evidence: The result should match the typed workload artifact—review, reproduction, documentation, analysis, migration, support answer, test, or release note—and preserve the run evidence used to reproduce it.
  • Failure behavior: Missing inputs, unavailable models, malformed typed output, denied commands, unsafe mutations, and exhausted limits fail without silently returning an unvalidated artifact.
  • Cleanup: These examples should leave external systems unchanged unless an approval-bound action explicitly says otherwise. Remove temporary clones, generated fixtures, and local run records after reviewing the result.
ExampleCommandWhat it proves
api-docs-generatorpnpm --dir examples/api-docs-generator run build
pnpm --dir examples/api-docs-generator run run
Generate MDX docs pages for HTTP routes. Demonstrates fumadocsSource to give the agent your existing docs as a tone/structure reference.
bug-reproducerpnpm --dir examples/bug-reproducer run build
pnpm --dir examples/bug-reproducer run run
Convert a free-form bug report into a minimal failing test. Pure inference — no shell required, runs anywhere.
changelog-writerpnpm --dir examples/changelog-writer run build
pnpm --dir examples/changelog-writer run run
Generate a Keep-a-Changelog markdown section between two git refs.
code-reviewpnpm --dir examples/code-review run buildProvides separate read-only code-review and pr-review agents that return typed findings and a final recommendation for local source or a GitHub pull request.
data-analystpnpm --dir examples/data-analyst run buildAnalyzes a CSV inside a network-isolated Docker sandbox and stores reproducible analysis.md and summary.json artifacts in the Harness session store.
dependency-auditorpnpm --dir examples/dependency-auditor run build
pnpm --dir examples/dependency-auditor run run
Run npm / pnpm audit and ask the model to prioritize the findings.
incident-runbookpnpm --dir examples/incident-runbook run build
pnpm --dir examples/incident-runbook run run
Match an alert to a mounted runbook (Fumadocs/Mintlify MDX) and walk through diagnostic steps. Read-only — never executes.
issue-triage-cipnpm --dir examples/issue-triage-ci run buildRuns a cautious CI issue-triage agent that is read-only by default, emits inspectable artifacts, denies publishing operations, and approval-gates issue comments.
release-notespnpm --dir examples/release-notes run build
pnpm --dir examples/release-notes run run
Customer-facing release notes from merged PRs between two tags.
schema-migrationpnpm --dir examples/schema-migration run build
pnpm --dir examples/schema-migration run run
Draft a SQL migration with up/down statements. Apply commands are gated behind approval in complete entrypoint.
support-agentpnpm --dir examples/support-agent run buildA customer support agent that answers questions by searching a knowledge base. The knowledge base is just a directory of markdown files mounted into the agent's sandbox — no vector store, no embeddings, no retrieval pipeline.
support-agent-cloudflare-r2pnpm --dir examples/support-agent-cloudflare-r2 run buildSupport-agent example that mounts a Cloudflare R2 bucket prefix into the Fabric sandbox as normal files.
support-agent-foundrypnpm --dir examples/support-agent-foundry run buildSupport-agent example shaped for Microsoft Foundry Hosted Agents.
test-generatorpnpm --dir examples/test-generator run build
pnpm --dir examples/test-generator run run
Generate a Vitest spec for a TypeScript source file. Includes a fixtures/src/util.ts so run works clean.

Databricks workloads

Progress from credential-free composition to target-workspace identity, governed data and AI access, native resource authoring, App bindings, durability, and protected certification.

  • Prerequisites and authentication: Run the mock or local contract first. Live paths require Databricks OAuth, least-privilege workspace and Unity Catalog permissions, the documented SKU or preview, and the exact resource identifiers named by the workspace.
  • Expected evidence: A local check proves Harness composition only. A live proof must record target-workspace preflight, identity, native service evidence, bounded agent behavior, cleanup, and the certification tier that actually ran.
  • Failure behavior: Authentication, authorization, preview, policy, stale-fingerprint, ambiguous-write, cancellation, timeout, and native terminal failures remain explicit. Non-idempotent or ambiguous writes are not retried automatically.
  • Cleanup: Trash or delete only the exact Harness-owned temporary resource in a finally path, wait for the native terminal state, then remove its ownership record. Never remove a pre-existing customer resource as example cleanup.
ExampleCommandWhat it proves
with-analytics-copilotpnpm --dir examples/with-analytics-copilot run build
pnpm --dir examples/with-analytics-copilot run start
Separates safe single-statement SQL reads from approval-bound arbitrary SQL and Genie management, with local validation before any Databricks call.
with-databrickspnpm --dir examples/with-databricks run build
pnpm --dir examples/with-databricks run run
Lighthouse use case #1 from the Databricks platform plan: a governed analytics copilot that answers questions over the lakehouse, with Unity Catalog enforcing access and Fabric adding approval routing, lineage, and an egress allowlist on top.
with-databricks-agent-servicepnpm --dir examples/with-databricks-agent-service run test
pnpm --dir examples/with-databricks-agent-service run start
This example registers an externally hosted Fabric Harness agent in Unity Catalog, verifies discovery and metadata updates, reads its grants, optionally exercises grant/revoke, and deletes the temporary registration. It defaults the external route to the Harness /responses endpoint. Agent Services is not yet represented in the modular TypeScript SDK, so Fabric keeps its preview transport private and exposes this lifecycle through the typed databricks() bundle.
with-databricks-app-resourcespnpm --dir examples/with-databricks-app-resources run check
pnpm --dir examples/with-databricks-app-resources run build
Build a Fabric Harness agent as a Databricks App while keeping Databricks Apps, Declarative Automation Bundles, Unity Catalog, Jobs, Model Serving, SQL Warehouses, and Databricks Secrets authoritative.
with-databricks-appkit-interoppnpm --dir examples/with-databricks-appkit-interop run test
pnpm --dir examples/with-databricks-appkit-interop run start
This runnable spike pins @databricks/appkit 0.53.0 and proves the safe additive boundary: an AppKit beta agent discovers and invokes a read-only tool exposed by Fabric Harness over MCP. The Harness server remains authoritative for authenticated identity, tenant context, policy version, canonical argument digest, cancellation signal, and tool-call evidence.
with-databricks-authoring-adminpnpm --dir examples/with-databricks-authoring-admin run build
pnpm --dir examples/with-databricks-authoring-admin run run
Combines custom-model serving endpoint management, non-destructive Unity Catalog administration, workspace notebook writes, and secret-reference writes. All surfaces are opt-in and route to the platform-admin approval audience. The secret tool receives {kind:'secret', name} and resolves APP_RUNTIME_SECRET server-side; raw material never enters model tool input or lineage.
with-databricks-bundle-deploypnpm --dir examples/with-databricks-bundle-deploy run build
pnpm --dir examples/with-databricks-bundle-deploy run run
Validates, deploys, and runs a checked-in Databricks Asset Bundle (DAB) through governed model tools. Harness does not generate the bundle YAML — bundle/databricks.yml and its notebooks stay checked-in infrastructure-as-code. The agent owns only the lifecycle: databricks_bundle_validate is read-only, while databricks_bundle_deploy, databricks_bundle_run, and databricks_bundle_destroy are mutations that require data-platform steward approval. Deploy records a sha256 fingerprint of the bundle source tree in a managed-resource store, so drift and foreign deployments are detected instead of stomped. After deploy, the agent can kick off a run of a bundle-defined job or pipeline by its databricks.yml resource key with databricks_bundle_run; submission is always --no-wait, and run status is polled through the bounded jobs/lakeflow status tools rather than waited on inside the tool call.
with-databricks-computepnpm --dir examples/with-databricks-compute run test
pnpm --dir examples/with-databricks-compute run start
Keeps SQL Warehouses, SQL-backed portable sandboxes, asynchronous Jobs, one-off notebook submission, and Databricks App hosting as distinct execution choices.
with-databricks-cost-attributionpnpm --dir examples/with-databricks-cost-attribution run build
pnpm --dir examples/with-databricks-cost-attribution run start
Demonstrates databricksTenantCostLimit with a mocked generated Statement Execution client, so the example runs without any environment variables or a live warehouse.
with-databricks-dataengpnpm --dir examples/with-databricks-dataeng run build
pnpm --dir examples/with-databricks-dataeng run run
Lighthouse use case #3 from the Databricks platform plan: a data-engineering agent that manages Lakeflow Declarative Pipelines (DLT) and inspects Delta tables, under Unity Catalog governance, on a Temporal worker. Pipeline runs are among the heaviest continuous-compute consumption surfaces.
with-databricks-genie-authoringpnpm --dir examples/with-databricks-genie-authoring run test
pnpm --dir examples/with-databricks-genie-authoring run run:lifecycle
Teaches approval-gated Genie authoring, Agent Mode invocation of an existing resource, and a complete two-identity lifecycle with exact-resource cleanup in finally.
with-databricks-jobs-authoringpnpm --dir examples/with-databricks-jobs-authoring run build
pnpm --dir examples/with-databricks-jobs-authoring run run
Creates, verifies, runs/repairs, explicitly updates, and deletes a multi-task Databricks Job through governed model tools. Every write/execute requires data-platform steward approval. Classic compute must use the configured Databricks cluster policy and stays within worker, concurrency, timeout, runtime, node-type, and tag bounds.
with-databricks-managed-mcppnpm --dir examples/with-databricks-managed-mcp run build
pnpm --dir examples/with-databricks-managed-mcp run start
This runnable example connects Harness's Databricks adapter to a local Streamable HTTP MCP server, discovers one explicitly allowed tool, invokes it under a rotating OBO credential, and records a governed lineage event. The local server stands in for Databricks managed Genie MCP, so no workspace or credentials are required.
with-databricks-ragpnpm --dir examples/with-databricks-rag run build
pnpm --dir examples/with-databricks-rag run run
Lighthouse use case #2 from the Databricks platform plan: a RAG support agent that answers from a Databricks AI Search knowledge base, with a Unity AI Gateway model service reasoning over the retrieved passages under Unity Catalog governance.
with-databricks-rag-adminpnpm --dir examples/with-databricks-rag-admin run build
pnpm --dir examples/with-databricks-rag-admin run run
Demonstrates endpoint and delta-sync index lifecycle alongside the existing governed query tool. Set Databricks OAuth credentials plus DATABRICKS_CATALOG, DATABRICKS_EXISTING_INDEX, and DATABRICKS_TEXT_COLUMN; the principal needs Vector Search endpoint/index administration and SELECT on the source Delta table. aiSearchAdmin is bound to a resource policy, so also set DATABRICKS_ADMIN_ENDPOINT, DATABRICKS_ADMIN_INDEX (catalog-qualified), and DATABRICKS_EMBEDDING_ENDPOINT — those are the only endpoint, index, and embedding model the admin tools accept, pinned into the tool schemas and re-checked at call time. The embedding endpoint is bounded separately because the source column's contents are sent to it. Run pnpm build && pnpm run.
with-databricks-revenue-opspnpm --dir examples/with-databricks-revenue-ops run test
pnpm --dir examples/with-databricks-revenue-ops run run:mock
This is the opinionated customer reference for a governed, durable agent on Databricks. Databricks owns data, identity, Genie, the SQL Warehouse, the forecast Job, App hosting, Lakebase, and MLflow. Harness adds a bounded agent lifecycle, exact-operation approval, stable delivery identity, restart-safe submissions, and correlated terminal evidence.
with-databricks-simplepnpm --dir examples/with-databricks-simple run test
pnpm --dir examples/with-databricks-simple run run
Minimal runnable Fabric Harness example that demonstrates the Databricks happy path with mocked APIs — no real credentials required.

Provider evidence and release claims

Provider-backed examples have three distinct evidence levels:

  1. Local contract: types, policy, serialization, and failure behavior pass without provider credentials.
  2. Live smoke: the named account, workspace, region, identity, and resource pass one bounded run and cleanup.
  3. Protected certification: retained evidence meets the release gate and scope stated by that provider's certification page.

Do not turn a build, mock run, optional probe, preview enrollment, or single-region smoke into a general production claim. Databricks claims must match the current public certification record.