Blueprints

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

Blueprints

A Blueprint is a declarative, idempotent description of the agents and Surface squads your application wants to ensure for one principal. Use it to give every new workspace, tenant, or signed-in principal the same dependable starting team.

Blueprints in 2.0: top-level squads

Blueprints can include a canonical squads collection with orchestrator or task compositions. Swarm-era nested squad configuration has been removed. See Surface Squads for schemas, roles, health, and migration.

Blueprints are application-driven

FabrCore does not discover, store, or run Blueprints automatically when the Host starts. Your application calls the Blueprint endpoint when it provisions a principal—for example, after first sign-in, tenant creation, or workspace initialization.

What Blueprints Solve

Without a Blueprint, every client or provisioning flow has to decide whether each agent already exists, whether it is configured, and whether it is safe to overwrite. A Blueprint turns that into one repeatable ensure operation.

For developers

Keep workspace composition close to application code: agent aliases, prompts, plugins, tools, MCP servers, streams, models, arguments, and top-level squad membership use versionable contracts.

For administrators

Apply the same baseline safely for each principal without replacing agents that are already configured. The response shows each agent's health, so provisioning can be observed and retried deliberately.

Apply a Blueprint

Post an AgentBlueprintRequest to POST /fabrcoreapi/Agent/blueprint. The x-user-handle header identifies the target principal.

HTTP request

POST /fabrcoreapi/Agent/blueprint
x-user-handle: acme-42

{
  "name": "support-workspace",
  "version": "2026-07",
  "agents": [
    {
      "handle": "assistant",
      "agentType": "chat-agent",
      "models": "default",
      "systemPrompt": "Help triage support work.",
      "plugins": ["Tickets"],
      "args": { "Tickets:Queue": "support" }
    }
  ]
}

The typed SDK wraps the same operation:

C# — application provisioning

var result = await hostApi.EnsureBlueprintAgentsAsync(
    principalHandle,
    new AgentBlueprintRequest
    {
        Name = "support-workspace",
        Version = "2026-07",
        Agents = [new AgentConfiguration
        {
            Handle = "assistant",
            AgentType = "chat-agent",
            Models = "default"
        }]
    },
    cancellationToken: cancellationToken);

Lifecycle and Idempotency

Agent state for this principal	Blueprint result
Not tracked yet	FabrCore configures the agent and adds it to the principal's tracked-agent list.
Tracked and configured	FabrCore returns health without intentionally changing its configuration. This includes healthy, degraded, and unhealthy configured agents.
Tracked but `NotConfigured`	FabrCore configures it from the Blueprint.
One agent fails to configure	That result is unhealthy; FabrCore continues processing the remaining agents.

Safe to call more than once

Calling the same Blueprint during login or workspace bootstrap is safe. It ensures missing agents appear while protecting an already configured agent from an unplanned reset.

Handles and scope

A bare handle such as assistant is scoped to the header principal, becoming acme-42:assistant.
A fully-qualified handle is allowed only when its principal prefix matches x-user-handle.
Cross-principal Blueprint handles return 400 Bad Request.

Operational Guidance

Need	Use	Why
Give a principal its standard agents	`POST /agent/blueprint`	Ensures the baseline without replacing configured agents.
Deliberately change an existing agent	`POST /agent/create`	Use `ForceReconfigure` when a controlled reconfiguration is intended.
Remove an agent from a principal	`DELETE /agent/{handle}`	Blueprints do not delete agents omitted from a later version.

Name and Version help your application trace which Blueprint it sent. FabrCore echoes them in the response but does not persist, compare, or automatically migrate versions. Treat a new version as a deployment decision: use a Blueprint to ensure additions, and use /agent/create where you intentionally want an existing agent changed.

Recommended rollout

Define the baseline in application code, call it at your principal-creation or first-sign-in boundary, log each AgentHealthStatus, and alert on non-healthy results. This gives developers a single provisioning contract and gives operators an observable, repeatable process.

Cloud blueprint management

The 2.0 administration workflow adds typed paged summaries, conditional CRUD, clone/import/export, validation, expansion previews and persisted per-agent deployment results. Preserve all extension JSON, including optional Surface squads. A summary object is not the legacy blueprint-name list.

Review the saved revision and expanded configuration digest before deployment. Ensure creates missing agents; update also reconfigures existing agents. Neither deletes removed agents. Custom effect-free preview extensions implement IBlueprintPreviewExpander. Cloud envelopes use the same cluster-coordinated service, with optional DeploymentId/ApplyMode and compatible defaults. Explicit selected-item retries retain results; uncertain work is not replayed automatically.

Insights distinguishes cloud-managed and runtime-only definitions and shows deployed revisions and definition drift. Automatic live-agent configuration drift detection is not implemented.

Reusable connection bindings

The top-level connectedAgents extension binds connection aliases and remote agents. $principal resolves at deployment. Profiles and grants are provisioned separately; preview does not perform consent or acquire tokens. Read the integration guide.