Home / Docs / Blueprints

Blueprints

Blueprints

A Blueprint is a declarative, idempotent list of agents 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 of agents.

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 the standard workspace composition close to application code: agent aliases, prompts, plugins, tools, MCP servers, streams, models, and arguments all use the familiar AgentConfiguration shape.

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 principalBlueprint result
Not tracked yetFabrCore configures the agent and adds it to the principal's tracked-agent list.
Tracked and configuredFabrCore returns health without intentionally changing its configuration. This includes healthy, degraded, and unhealthy configured agents.
Tracked but NotConfiguredFabrCore configures it from the Blueprint.
One agent fails to configureThat 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

NeedUseWhy
Give a principal its standard agentsPOST /agent/blueprintEnsures the baseline without replacing configured agents.
Deliberately change an existing agentPOST /agent/createUse ForceReconfigure when a controlled reconfiguration is intended.
Remove an agent from a principalDELETE /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.

Documentation