Migrate from legacy agent APIs

This guide is for projects created before the current agent and route model. The unqualified documentation on this site describes the stable releases listed on release status.

Builder and workspace changes

Finite work now uses defineAgent() and lives in .fabricharness/jobs/. Persistent, addressable agents use createAgent() and live in .fabricharness/agents/.

.fabricharness/
  jobs/
    nightly-report.ts
  agents/
    support-agent.ts

Replace retired finite builders named agent(), job(), or defineJob() with defineAgent(). There are no compatibility aliases in the supported public API.

Route changes

• Invoke a finite definition with POST /jobs/:name.
• Address a persistent definition with POST /agents/:name/:id.
• Use @fabric-harness/client for typed job invocation, durable submissions, conversation reads, observation, cancellation, and persistent-agent prompts.

Code that invokes a finite definition through /agents/:name/:id must move to /jobs/:name. Treat a 410 response from the retired route as a migration error, not as a retryable failure.

Runtime and package changes

1. Upgrade the CLI first and run fh capabilities --json.
2. Keep the SDK, CLI, Node runtime, and generated template ranges emitted by the same CLI release.
3. Check every optional integration independently; package major versions are not synchronized.
4. Rebuild generated targets instead of copying an older .fabricharness/build/ directory.
5. Run mock tests before enabling provider credentials or live deployment.

The default SDK entry point supplies documented headless defaults. The @fabric-harness/sdk/strict entry point preserves explicit finite-agent configuration and does not silently inject those defaults. Recheck imports when migrating Temporal or compliance-sensitive workloads.

Verification

npx fh --version
npx fh capabilities --json
npx fh doctor --getting-started --tools --model mock/test-model
npx fh agents --json

Then run the relevant deployment build and inspect its manifest before promotion. See build artifacts and production readiness.