Surface Squads

Blueprint-defined multi-agent coordination

Surface squads group agents behind one generated coordinator. v1.7.1 replaces the retired Swarm runtime with two smaller, explicit shapes: orchestrator for one-hop routing and task for Harness-driven multi-step work.

Canonical blueprint shape

Squads are a top-level extension on FabrCoreBlueprint. Store the same JSON in source control, apply it locally, and distribute it through an administrative workflow.

{
  "name": "support-workspace",
  "version": "1.7.1",
  "squads": [
    {
      "squadType": "task",
      "name": "Ops Desk",
      "orchestratorModel": "default",
      "taskOptions": {
        "workerModelName": "default",
        "personaPrompt": "Coordinate carefully and cite member results.",
        "delegationTimeoutSeconds": 120,
        "maxLoopIterations": 10
      },
      "agents": [
        {
          "name": "incident-data",
          "agentType": "incident-data-agent",
          "role": "executor"
        },
        {
          "name": "policy-desk",
          "agentType": "policy-agent",
          "role": "subjectMatterExpert"
        }
      ]
    }
  ]
}

Apply directly with POST /fabrcoreapi/Agent/blueprint and x-user-handle, or store the document with PUT /fabrcoreapi/Blueprint/{name} and apply it later.

Orchestrator squads

An orchestrator squad loads healthy member capabilities, classifies the request, and sends it to the best single member. Choose it when the work belongs to one specialist and a multi-step plan would add unnecessary latency and cost.

Task squads

A task squad provisions SurfaceTaskHarnessAgent. During one request it:

1. Creates a model-owned todo list with todos_*.
2. Delegates independent work concurrently to Executor members.
3. Consults SubjectMatterExpert members for advice without assigning them execution ownership.
4. Collects results through background_agents_*.
5. Reinvokes the coordinator until no todos or delegations remain, or the iteration budget is reached.

Member roles

Descriptions and capabilities matter. They are the routing contract the coordinator sees. State both what a member does and when it should not be selected.

Task options

Health and generated handles

• Generated coordinator handles use squad-{slug}; members use squad-{slug}-{member}.
• Members are health-probed during activation. Unhealthy members are excluded from the roster and surfaced in coordinator health metrics.
• Delegations travel through FabrCore messaging and remain subject to ACL and monitoring.
• The command center hides internal generated agents by default while presenting the squad as the user-facing target.

Migrate from Swarm

Change the nested extension:

{ "swarm": { "squads": [ ... ] } }

to the top-level extension:

{ "squads": [ ... ] }

• Replace squadType: "swarm" with orchestrator or task.
• Replace FabrCore.Surface.Ai.Swarm APIs and SurfaceSwarm* types with FabrCore.Surface.Ai.Squads, FabrCore.Surface.Ai.Tasks, ISurfaceSquadService, and SurfaceTaskHarnessAgent.
• Remove assumptions about the former Swarm planner, supervisor, verifier, budgets, and wire messages.
• Reapply stored blueprints so the new expander provisions the replacement topology.