Server

Server

The FabrCore server hosts your agents on an Orleans cluster. It provides REST and WebSocket APIs for client communication and background services for housekeeping.

Extension Methods

AddFabrCoreServer

Configures FabrCore server infrastructure including Orleans, services, and streaming.

var builder = WebApplication.CreateBuilder(args);

// Basic setup
builder.AddFabrCoreServer();

// With additional assemblies for custom agents
builder.AddFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new List<Assembly>
    {
        typeof(MyCustomAgent).Assembly
    }
});

What it configures:

• Orleans silo with clustering, persistence, and reminders
• IFabrCoreRegistry (singleton) — Agent, plugin, and tool discovery
• IFabrCoreChatClientService (singleton) — Chat client factory
• IEmbeddings (singleton) — Embedding generation with cached client
• IFileStorageService (singleton) — File storage with TTL
• FileCleanupBackgroundService — Automatic file cleanup
• AgentRegistryCleanupService — Automatic agent registry cleanup

UseFabrCoreServer

Registers FabrCore middleware, including the WebSocket endpoint for real-time agent communication.

var app = builder.Build();

app.UseFabrCoreServer();

// Or with options
app.UseFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new List<Assembly> { typeof(MyAgent).Assembly }
});

Complete Startup Example

var builder = WebApplication.CreateBuilder(args);

builder.AddFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new() { typeof(MyAgent).Assembly }
});

builder.Services.AddControllers();

var app = builder.Build();

app.UseFabrCoreServer();
app.MapControllers();

await app.RunAsync();

FabrCoreRegistry

FabrCoreRegistry automatically discovers agents, plugins, and tools at startup by scanning loaded assemblies for alias attributes. No manual registration lists needed — decorate your classes and they're available.

Loading Additional Assemblies

If your agents, plugins, or tools are in separate assemblies, pass them via AdditionalAssemblies. This ensures the registry scans those assemblies at startup:

builder.AddFabrCoreServer(new FabrCoreServerOptions
{
    AdditionalAssemblies = new List<Assembly>
    {
        typeof(MyCustomAgent).Assembly,
        typeof(MyPluginLibrary).Assembly
    }
});

How Discovery Works

All attributes support AllowMultiple = true, so a single component can have multiple aliases:

[AgentAlias("assistant")]
[AgentAlias("my-assistant")]
public class AssistantAgent : FabrCoreAgentProxy
{
    // Reachable via either alias
}

Registry API

Discovery REST Endpoint

The registry is exposed via a built-in REST endpoint, allowing clients to discover available agents, plugins, and tools at runtime:

{
  "agents": [
    { "typeName": "MyApp.AssistantAgent", "aliases": ["assistant", "my-assistant"] }
  ],
  "plugins": [
    { "typeName": "MyApp.WeatherPlugin", "aliases": ["weather"] }
  ],
  "tools": [
    { "typeName": "MyApp.MathTools.Add", "aliases": ["add-numbers"] }
  ]
}

REST API

All endpoints are prefixed with /fabrapi.

Agent API

All Agent API endpoints require the x-user header to identify the user.

POST /fabrapi/Agent/create
x-user: user123

[{
  "handle": "my-agent",
  "agentType": "MyAgent",
  "models": "default",
  "systemPrompt": "You are a helpful assistant."
}]

Diagnostics API

File & Embeddings API

Batch Embeddings

The batch endpoint accepts a list of items, each with a caller-provided id and text:

{
  "items": [
    { "id": "item-1", "text": "First document to embed" },
    { "id": "item-2", "text": "Second document to embed" },
    { "id": "item-3", "text": "Third document to embed" }
  ]
}

{
  "results": [
    { "id": "item-1", "vector": [0.0123, -0.0456, ...], "dimensions": 1536 },
    { "id": "item-2", "vector": [0.0789, -0.0321, ...], "dimensions": 1536 },
    { "id": "item-3", "vector": [0.0654, -0.0987, ...], "dimensions": 1536 }
  ]
}

Validation Rules

Chat Completions API

FabrCore exposes an OpenAI-compatible chat completions endpoint via the ChatCompletionController, allowing external systems to interact with configured LLM models using standard OpenAI client libraries.

Endpoint

The endpoint uses IFabrCoreChatClientService to resolve the model by name from fabrcore.json. It is designed for single-turn completions — no streaming or tool calling.

Request Format

{
  "Messages": [
    { "Role": "user", "Content": "Extract entities from this text..." }
  ],
  "Options": {
    "Model": "gpt-4o-mini",
    "MaxOutputTokens": 2048,
    "Temperature": 0.2
  }
}

Options is optional. Supported options: Model (defaults to "default"), MaxOutputTokens, Temperature, TopP, TopK, StopSequences, FrequencyPenalty, PresencePenalty.

Response Format

{
  "Text": "The extracted response text...",
  "Model": "gpt-4o-mini",
  "Usage": { "InputTokens": 150, "OutputTokens": 80 }
}

WebSocket API

Real-time communication with agents via WebSocket at the /ws endpoint.

// Browser
const ws = new WebSocket('wss://your-server/ws?userid=user123');

// Send a message
ws.send(JSON.stringify({
  toHandle: "my-agent",
  fromHandle: "user123",
  message: "Hello, agent!"
}));

Authentication requires either the x-fabr-userid header or the userid query parameter.

Orleans Streaming

FabrCore uses Orleans streams for agent communication:

Background Services

SQL Server Auto-Provisioning

When using SqlServer clustering mode, FabrCore automatically provisions the required Orleans database tables at startup via OrleansSqlServerInitializer. No manual SQL scripts or database migrations are needed.

How It Works

The initializer runs embedded SQL scripts that create tables for all four Orleans subsystems under a dedicated orlns schema:

The SQL scripts are embedded resources within the FabrCore assembly. The initializer checks whether the schema and tables already exist before running, making it safe for repeated startups.

// appsettings.json — tables are auto-provisioned on first startup
{
  "Orleans": {
    "ClusterId": "prod",
    "ServiceId": "fabrcore",
    "ClusteringMode": "SqlServer",
    "ConnectionString": "Server=localhost;Database=FabrCore;Trusted_Connection=True;"
  }
}