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 initThen 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.
| Example | Command | What it proves |
|---|---|---|
agent-registry | pnpm --dir examples/agent-registry run checkpnpm --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-routes | pnpm --dir examples/application-routes run checkpnpm --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-persistence | pnpm --dir examples/database-persistence run checkpnpm --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-agent | pnpm --dir examples/dynamic-agent run buildpnpm --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-jobs | pnpm --dir examples/finite-jobs run checkpnpm --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-world | pnpm --dir examples/hello-world run build | Defines the functionally named hello and ask finite agents, then proves config defaults, credential-free mock execution, and optional durable Temporal execution. |
minimal | pnpm --dir examples/minimal run build | The 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-chat | pnpm --dir examples/react-chat run checkpnpm --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-jobs | pnpm --dir examples/scheduled-jobs run checkpnpm --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-approval | pnpm --dir examples/with-approval run build | Demonstrates policy-gated tool execution. |
with-checkpoint | pnpm --dir examples/with-checkpoint run buildpnpm --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-config | pnpm --dir examples/with-config run buildpnpm --dir examples/with-config run run | Demonstrates central workspace configuration through .fabricharness/config.ts. |
with-finish-tool | pnpm --dir examples/with-finish-tool run buildpnpm --dir examples/with-finish-tool run run | Demonstrates the finish / give_up result tool pattern for structured output. |
with-packaged-skills | pnpm --dir examples/with-packaged-skills run buildpnpm --dir examples/with-packaged-skills run run | Demonstrates packaged skills with lazy resource loading. |
with-signal-messages | pnpm --dir examples/with-signal-messages run buildpnpm --dir examples/with-signal-messages run run | Demonstrates session.createSignalEntry() for injecting typed signal entries into the session history. |
with-skill | pnpm --dir examples/with-skill run buildpnpm --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-task | pnpm --dir examples/with-task run buildpnpm --dir examples/with-task run run | Demonstrates parent/child task orchestration with shared durable session storage. |
with-tools | pnpm --dir examples/with-tools run buildpnpm --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.
| Example | Command | What it proves |
|---|---|---|
coding-agent-lite | pnpm --dir examples/coding-agent-lite run build | Clones 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-agent | pnpm --dir examples/remote-coding-agent run build | Provider-neutral remote sandbox example for coding agents. |
with-azure | pnpm --dir examples/with-azure run buildpnpm --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-sandbox | pnpm --dir examples/with-cloudflare-sandbox run buildpnpm --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-workspace | pnpm --dir examples/with-cloudflare-shell-workspace run buildpnpm --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-ai | pnpm --dir examples/with-cloudflare-workers-ai run buildpnpm --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-daytona | pnpm --dir examples/with-daytona run build | Runs a bounded shell workload in a Daytona-managed remote development sandbox. |
with-docker | pnpm --dir examples/with-docker run build | Runs standard Harness file and shell tools inside a Docker container with a scoped workspace mount. |
with-e2b | pnpm --dir examples/with-e2b run build | Runs a finite job in E2B, streams bounded command output, and removes the sandbox during session cleanup. |
with-kubernetes | pnpm --dir examples/with-kubernetes run buildpnpm --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-shell | pnpm --dir examples/with-local-shell run buildpnpm --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-modal | pnpm --dir examples/with-modal run build | Runs a finite Harness workload in a Modal serverless sandbox through the portable sandbox contract. |
with-postgres-store | pnpm --dir examples/with-postgres-store run buildpnpm --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-source | pnpm --dir examples/with-s3-source run buildpnpm --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-temporal | pnpm --dir examples/with-temporal run buildpnpm --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-sandbox | pnpm --dir examples/with-vercel-sandbox run build | Runs 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.
| Example | Command | What it proves |
|---|---|---|
operational-slos | pnpm --dir examples/operational-slos run test | Exports stable Harness operational metrics, evaluates the reference SLO policy, and validates importable Prometheus and Grafana assets. |
private-networking | pnpm --dir examples/private-networking run testpnpm --dir examples/private-networking run start | Proves that an allowed request succeeds through the configured proxy while a direct network bypass fails. |
voice-data-collector | pnpm --dir examples/voice-data-collector run build | Uses OpenAI Realtime to collect functionally named fields, submits typed submit_field calls, and persists the resulting field map in session memory. |
with-channel-adapters | pnpm --dir examples/with-channel-adapters run checkpnpm --dir examples/with-channel-adapters run dev | This runnable workspace mounts all 18 first-party channel adapters on one persistent agent. |
with-observability | pnpm --dir examples/with-observability run test | This 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-channel | pnpm --dir examples/with-slack-channel run buildpnpm --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.
| Example | Command | What it proves |
|---|---|---|
api-docs-generator | pnpm --dir examples/api-docs-generator run buildpnpm --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-reproducer | pnpm --dir examples/bug-reproducer run buildpnpm --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-writer | pnpm --dir examples/changelog-writer run buildpnpm --dir examples/changelog-writer run run | Generate a Keep-a-Changelog markdown section between two git refs. |
code-review | pnpm --dir examples/code-review run build | Provides 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-analyst | pnpm --dir examples/data-analyst run build | Analyzes a CSV inside a network-isolated Docker sandbox and stores reproducible analysis.md and summary.json artifacts in the Harness session store. |
dependency-auditor | pnpm --dir examples/dependency-auditor run buildpnpm --dir examples/dependency-auditor run run | Run npm / pnpm audit and ask the model to prioritize the findings. |
incident-runbook | pnpm --dir examples/incident-runbook run buildpnpm --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-ci | pnpm --dir examples/issue-triage-ci run build | Runs a cautious CI issue-triage agent that is read-only by default, emits inspectable artifacts, denies publishing operations, and approval-gates issue comments. |
release-notes | pnpm --dir examples/release-notes run buildpnpm --dir examples/release-notes run run | Customer-facing release notes from merged PRs between two tags. |
schema-migration | pnpm --dir examples/schema-migration run buildpnpm --dir examples/schema-migration run run | Draft a SQL migration with up/down statements. Apply commands are gated behind approval in complete entrypoint. |
support-agent | pnpm --dir examples/support-agent run build | A 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-r2 | pnpm --dir examples/support-agent-cloudflare-r2 run build | Support-agent example that mounts a Cloudflare R2 bucket prefix into the Fabric sandbox as normal files. |
support-agent-foundry | pnpm --dir examples/support-agent-foundry run build | Support-agent example shaped for Microsoft Foundry Hosted Agents. |
test-generator | pnpm --dir examples/test-generator run buildpnpm --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.
| Example | Command | What it proves |
|---|---|---|
with-analytics-copilot | pnpm --dir examples/with-analytics-copilot run buildpnpm --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-databricks | pnpm --dir examples/with-databricks run buildpnpm --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-service | pnpm --dir examples/with-databricks-agent-service run testpnpm --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-resources | pnpm --dir examples/with-databricks-app-resources run checkpnpm --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-interop | pnpm --dir examples/with-databricks-appkit-interop run testpnpm --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-admin | pnpm --dir examples/with-databricks-authoring-admin run buildpnpm --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-deploy | pnpm --dir examples/with-databricks-bundle-deploy run buildpnpm --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-compute | pnpm --dir examples/with-databricks-compute run testpnpm --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-attribution | pnpm --dir examples/with-databricks-cost-attribution run buildpnpm --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-dataeng | pnpm --dir examples/with-databricks-dataeng run buildpnpm --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-authoring | pnpm --dir examples/with-databricks-genie-authoring run testpnpm --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-authoring | pnpm --dir examples/with-databricks-jobs-authoring run buildpnpm --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-mcp | pnpm --dir examples/with-databricks-managed-mcp run buildpnpm --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-rag | pnpm --dir examples/with-databricks-rag run buildpnpm --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-admin | pnpm --dir examples/with-databricks-rag-admin run buildpnpm --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-ops | pnpm --dir examples/with-databricks-revenue-ops run testpnpm --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-simple | pnpm --dir examples/with-databricks-simple run testpnpm --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:
- Local contract: types, policy, serialization, and failure behavior pass without provider credentials.
- Live smoke: the named account, workspace, region, identity, and resource pass one bounded run and cleanup.
- 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.