Home / Docs / Upgrade to v1.7.1

Upgrade to v1.7.1

Upgrade from v1.6.3 to v1.7.1

v1.7.1 adds durable Harness agents, WebSocket v2, versioned per-principal Skills, the context compaction ladder, and simpler Surface squads. It also removes the legacy WebSocket and Swarm contracts. Use this checklist before deploying updated packages.

Full GitHub comparison Release announcement

1. Update packages

dotnet add package FabrCore.Host --version 1.7.1
dotnet add package FabrCore.Sdk --version 1.7.1

# New typed WebSocket client, when needed
dotnet add package FabrCore.Client.WebSocket --version 1.7.1

Keep all FabrCore packages on the same version line. v1.7.1 updates Microsoft Agent Framework packages to 1.16.0.

2. Migrate WebSocket clients

Breaking: The raw AgentMessage WebSocket protocol is removed.
  • Obtain one-time tickets from POST /fabrcoreapi/ws/ticket.
  • Offer the fabrcore.v2 and ticket subprotocols, then send hello.
  • Replace header/query principal selection with application authentication.
  • Use explicit async or requestResponse delivery mode.
  • Persist checkpoints, acknowledge durable deliveries, and handle gaps through HTTP resynchronization.
  • Provision agents through HTTP/blueprints; createagent is no longer a WebSocket operation.

Read the complete WebSocket v2 guide.

3. Replace Swarm definitions and APIs

Breaking: The Surface Swarm runtime and SurfaceSwarm* API surface are removed.
  • Move blueprint definitions from { "swarm": { "squads": [...] } } to top-level { "squads": [...] }.
  • Replace squadType: "swarm" with orchestrator or task.
  • Update code to FabrCore.Surface.Ai.Squads, FabrCore.Surface.Ai.Tasks, ISurfaceSquadService, and SurfaceTaskHarnessAgent.
  • Reapply stored blueprints after migration.

Read the Surface squads guide.

4. Configure the compaction ladder

  • Set both ContextWindowTokens and MaxOutputTokens for models used by tool-heavy or Harness agents.
  • Replace MidTurnCompactionEnabled and _MidTurnCompactionEnabled with ContextCompactionEnabled or _ContextCompactionEnabled.
  • Remove callers of FabrCoreRunStoppedException.CheckpointCount and consumers of _fabrcore_checkpoint_count.
  • Check startup logs for context:unconfigured and [OUT OF ORDER].
  • Do not disable history compaction unless unbounded persisted thread growth is acceptable.

Read the compaction ladder guide.

5. Adopt Harness behavior deliberately

  • Run Harness agents only through FabrCoreHarnessResult.RunAsync.
  • Pass AgentMessage.Args["_plan-mode"] = "false" for execution runs. Omitted or invalid values select planning by default.
  • Set MissingPlanModeBehavior when omitted flags should preserve the current mode or select execution.
  • Keep iteration and delegation budgets finite.
  • Report remaining todos and delegations marked lost after deactivation.

Read the Agent Harness guide.

6. Publish versioned Harness Skills

  • Package one SKILL.md plus supported textual resources in a ZIP.
  • Publish exact immutable versions through the FabrCoreAdmin-protected API.
  • Pin exact name@version references in _HarnessSkills.
  • Use durable Orleans storage if Skills must survive Host restarts.

Read the Harness Skills guide.

7. Update model-configuration authentication

Security change: /fabrcoreapi/ModelConfig/* now requires the FabrCoreAdmin policy.
  • Remote SDK processes must configure FabrCore:AdminAuthentication:ApiKey and send its bearer credential.
  • In-process Host agents need no loopback HTTP credential; v1.7.1 resolves model settings and keys directly from the active configuration store.
  • Expect explicit errors for redirects, HTML login pages, unauthorized responses, and malformed JSON.

8. Simplify assembly discovery

  • Remove routine AdditionalAssemblies entries for the application assembly and referenced FabrCore projects/packages.
  • Keep AdditionalAssemblies only for dynamically selected assemblies outside the dependency graph.
  • Use RegistryAssemblies when the Host needs an exact allowlist. An empty list intentionally creates an empty registry.

9. Validate operational fixes

  • Cloud Server connect polling now has a dedicated poll-aware timeout and retry path. Remove workarounds written around application-wide 10-second Polly timeouts.
  • Microsoft 365 Copilot streaming now stops the typing timer before the final success or error activity. Verify custom bridge overrides preserve that ordering.

Deployment checklist

  • Build and run the Host and affected client test suites.
  • Exercise WebSocket disconnect/reconnect, duplicate delivery, and gap recovery.
  • Apply migrated squad blueprints to a non-production principal.
  • Run a Harness agent through planning, execution, timeout, deactivation, and restore.
  • Verify remote model-config callers receive JSON with a valid bearer key and 401 without one.
  • Confirm durable storage is configured for production Harness state, Skills, agent state, and delivery grains.
Start with the Harness Migrate WebSockets Migrate squads
Documentation