Learn Fabric Harness

Fabric Harness has a broad surface, but you should not learn it as a list of exports. Start with one agent lifecycle, add only the capabilities the workload needs, and prove each boundary before moving to the next stage. This page is the canonical map for the complete framework.

Choose the first outcome

The learning sequence

1. Learn the two agent lifecycles

Read Agent APIs, then build both forms:

• defineAgent() is a finite, bounded invocation that returns one result.
• createAgent() is a persistent, addressable agent initialized for each interaction.

Use Agent anatomy for finite definitions and Dynamic agents and hooks for persistent composition. Then inspect the definition with fh agents and fh describe before running it.

Practice with hello-world, minimal, finite-jobs, and dynamic-agent in the example catalog. Do not proceed until you can explain where termination bounds, static policy, interaction state, and initialization belong.

2. Build context deliberately

Add context one layer at a time:

1. Sessions and prompts for the conversation boundary.
2. Roles for instruction overlays.
3. Skills for Markdown-first procedures.
4. Session memory and context compaction for bounded continuity.
5. Filesystem sources and artifacts for mounted knowledge and retained output.

Practice with with-skill, with-packaged-skills, with-s3-source, data-analyst, and support-agent. Verify what enters model context, what remains server-side, and what is retained after deletion.

3. Give the agent capabilities

Use Tools for typed model calls, Commands for shell capabilities, Tasks and Subagents for delegation, and MCP for remote tool discovery.

Every capability needs:

• a schema and effect classification;
• a definition-level policy floor;
• bounded output, timeout, cancellation, and concurrency;
• explicit secret resolution outside model context; and
• deterministic failure behavior that callers can distinguish from cancellation or exhaustion.

Practice with with-tools, with-finish-tool, with-task, with-local-shell, with-signal-messages, and application-routes.

4. Isolate execution

Start with the sandbox guide, choose a backend using the sandbox matrix, and learn the portable sandbox lifecycle. Use sandbox connectors when the environment is provider-managed.

The full path covers virtual, local, Docker, Kubernetes, Cloudflare Computer, Cloudflare Sandbox, Databricks SQL, Daytona, E2B, Modal, and Vercel Sandbox. Provider pages under Ecosystem → Sandboxes document authentication and unsupported operations. Practice with the matching with-* workspace and verify create, exec, files, timeout, cancellation, and cleanup—not only a successful command.

5. Add governance before mutation

Read Policies and approvals, then the guided Approvals and Enterprise controls pages. Continue with:

• Authentication and RBAC;
• Multi-tenancy;
• Rate limiting;
• Private networking;
• Secrets, retention, and residency; and
• Security hardening.

Practice with with-approval, private-networking, with-analytics-copilot, and the Databricks authoring workspaces. Test one allowed action, one policy denial, one expired or rejected approval, and one cross-tenant access attempt.

6. Make accepted work durable

Read Runtime modes, Session stores, and Build and run artifacts. Then add:

• checkpoints and replay with with-checkpoint;
• unified database persistence with database-persistence;
• durable child work with with-task and finite-jobs;
• Temporal activities and deterministic workflows with Temporal Worker; and
• recovery objectives with Backup and disaster recovery.

The durability proof is a restart, cancellation, retry-classification, and idempotency test. A successful uninterrupted run is not durability evidence.

7. Choose models, data, and retrieval

Use Model providers for OpenAI-compatible, Anthropic, Bedrock, Vertex, Azure, Databricks, Workers AI, and custom providers. Use Databases for SQLite, libSQL/Turso, Postgres, Lakebase, MySQL, MongoDB, Redis/Valkey, and Supabase patterns.

For knowledge workloads, choose mounted files, a database tool, MCP, or provider-native retrieval based on the data boundary. The use-case guide compares those approaches. Databricks AI Search and governed RAG have their own RAG path.

8. Deliver through the right interface

The same runtime can be reached through:

• the CLI, fh fiber, schedules, and webhooks;
• the authenticated HTTP server;
• @fabric-harness/client and React hooks;
• Channels, including every adapter in Ecosystem → Channels; and
• Voice with a selected voice provider.

Practice with react-chat, scheduled-jobs, with-channel-adapters, with-slack-channel, and voice-data-collector. Validate signature/authentication failures, duplicate delivery, retries, stream reconnection, and identity propagation.

9. Build and deploy portably

Learn fh build, fh deploy, build manifests, package verification, and target-specific preflight from Deployment overview. The maintained paths cover Node, Docker, Temporal, Cloudflare, Azure/ACI/AKS, Foundry Hosted Agents, Databricks Apps and serving proxies, AWS/SST, Fly.io, Railway, Render, GitHub Actions, and GitLab CI. Remote sandbox providers are execution backends and do not replace the deployment runtime.

For each target, follow its page through prerequisites, build, validation, expected health result, failure behavior, and cleanup. Use Portable agent packages when another repository consumes the artifact.

10. Operate and improve the system

Use Agent events, Telemetry, and Cost attribution before production traffic. Add:

• Evaluations and the eval library;
• Operator Console;
• Operational SLOs;
• Audit export;
• Supply-chain evidence; and
• the production readiness checklist and current validation status.

Practice with with-observability and operational-slos. Prove redaction, correlation, alerting, retention, deletion, and recovery instead of treating emitted logs as sufficient observability.

11. Learn the Databricks path in order

Databricks owns data, models, identity, compute, governance, and hosting. Harness owns the portable, durable agent-control boundary around those services.

1. Choose a workload and read why Harness.
2. Complete the quickstart and local naming/authentication.
3. Choose native services from Databricks integrations: AI Gateway and Model Serving, SQL, Unity Catalog, AI Search, RAG, Genie, Jobs, Lakeflow, Feature Serving, Lakebase, MLflow, managed MCP, Agent Services, Supervisor Agents, Knowledge Assistants, managed memory, Apps, and ResponsesAgent.
4. Learn approval-bound writes in resource management, including Jobs, Lakeflow, AI Search, Serving, Unity Catalog, Workspace, secret references, Asset Bundles, and Genie Agents.
5. Use the dedicated Genie Agent Mode path for the explicit Beta create, permission, streaming, model-tool, failure, and cleanup journey.
6. Deploy through the Databricks App tutorial and add Lakebase or Temporal durability when the workload requires it.
7. Check workspace compatibility and live certification, then compare the exact package and target against validation status before making a production claim.

Preview availability is workspace-dependent. Contract support, a successful optional live probe, and release-blocking certification are different claims and remain labeled separately.

Complete feature-family map

Public package map

How to know a feature is learned

For every feature you adopt, keep six things together:

1. Prerequisites: runtime, package, provider, authentication, permissions, and preview/SKU needs.
2. Minimal path: the smallest public-API configuration that demonstrates the capability.
3. Expected result: observable output, event, artifact, state transition, or health response.
4. Failure path: at least one denial, invalid input, cancellation, timeout, or unavailable-provider test.
5. Cleanup: the exact resource, store, session, sandbox, or deployment reclamation action.
6. Evidence: a deterministic test locally and a provider-backed smoke or certification record where the feature depends on managed infrastructure.

The example catalog is indexed by these expectations. API signatures remain in the generated reference; the reference is a lookup tool, not the learning order. Use Runnable examples for synchronized commands, expected evidence, provider limitations, failure behavior, and cleanup across every workspace.