Runiq AI

Build AI agents in C#. Run them inside your ASP.NET Core application.

Runiq AI is a code-first agent runtime for .NET. Define agents and strongly typed tools, stream model responses, ground answers in your documents, and orchestrate workflows using your application's hosting and dependency injection. An embedded dashboard lets you explore agents, try conversations, and inspect runtime activity.

Quickstart · Packages · Samples · Build and test · Documentation

What you can build

• Agents with tools: C# agent definitions, typed tool inputs and outputs, provider integration, and streaming execution.
• Document assistants: ingestion, chunking, embeddings, retrieval, grounding policies, source citations, and optional reranking.
• Persistent knowledge stores: PostgreSQL and pgvector integration for durable documents and vector search.
• Agent workflows: code-first orchestration with runtime and dashboard integration.
• MCP services: expose application capabilities to MCP-compatible clients over HTTP.
• Application-owned dashboards: host the dashboard in your ASP.NET Core process with configurable authentication.

Quickstart

You need the .NET 10 SDK and an OpenAI API key for this example.

1. Create an application

dotnet new web -n MyRuniqApp
cd MyRuniqApp
dotnet add package Runiq.AI.Agents --version 1.0.0
dotnet user-secrets init
dotnet user-secrets set "OpenAI:ApiKey" "YOUR_OPENAI_API_KEY"

Runiq.AI.Agents includes the agent registration API and references Runiq.AI.Core, Runiq.AI.Rag, and Runiq.AI.Memory. You do not need to install those dependencies separately for this example. Memory remains disabled until explicitly configured; its foundation does not yet persist or replay conversations.

2. Replace Program.cs

using Runiq.AI.Agents;
using Runiq.AI.Core;

var builder = WebApplication.CreateBuilder(args);
var apiKey = builder.Configuration["OpenAI:ApiKey"]
    ?? throw new InvalidOperationException("Configure OpenAI:ApiKey before starting the app.");

builder.Services.AddRuniqServer(options =>
{
    options.AddAgent(new Agent(
        id: "assistant",
        name: "Assistant",
        instructions: "You are a helpful assistant. Give clear, concise answers.",
        model: "openai/gpt-5",
        apiKey: apiKey));
});

var app = builder.Build();

app.UseRuniqDashboard(options =>
{
    options.Path = "/dashboard";
    options.Title = "My Runiq App";
    options.Authentication(auth =>
    {
        // Local demo only. Configure authentication before deploying.
        auth.AllowAnonymous();
    });
});

app.Run();

3. Run and explore

dotnet run --environment Development --urls http://localhost:5050

Open localhost:5050/dashboard, select Assistant, and start a conversation. Model requests use your configured provider credentials.

For authenticated hosting, see the user-based and role-based security samples.

Prefer scaffolding? Install the Runiq CLI and run its project wizard:

dotnet tool install --global Runiq.AI.Cli --version 1.0.0
runiq init MyRuniqApp

Packages

Choose packages by capability. Package guides include configuration and API examples.

Package	Purpose	Guide
Runiq.AI.Agents	Agent definitions, typed tools, providers, streaming, and execution results	Agents
Runiq.AI.Core	Shared contracts, ASP.NET Core hosting, runtime endpoints, and embedded dashboard	Core
Runiq.AI.Memory	Opt-in Memory identity, configuration, and ownership foundations; no transcript persistence/replay yet	Memory
Runiq.AI.Rag	Document ingestion, chunking, embeddings, vector storage, and retrieval	RAG
Runiq.AI.Rag.PostgreSql	PostgreSQL persistence and pgvector search	PostgreSQL
Runiq.AI.Workflows	Code-first workflow definitions and execution	Workflows
Runiq.AI.Mcp	MCP server integration and application tools	MCP
Runiq.AI.Cli	.NET tool for scaffolding applications	CLI

Memory dependencies follow Agents -> Memory -> Core. The planned Memory.PostgreSql -> Memory provider (#200) is an explicit install, and the optional Memory.Rag -> Memory + Rag adapter (#207) is separate. Neither is shipped by #199. See the Memory responsibility and acceptance map.

Ground answers in your documents

RAG agents support three execution modes: Open, Grounded, and Required. Configure what happens when no acceptable context is found, apply relevance thresholds, and optionally rerank accepted candidates before selecting context.

• Grounding policies and relevance acceptance
• Cohere reranking configuration
• Answerability and failure behavior
• Provider-neutral reranking contract

Agent Chat distinguishes selected grounding evidence from validated source citations. Citation validation checks source identity; it does not establish that a source supports every sentence. Remote reranking sends the query and candidate chunk text to the configured provider; review the operational and security criteria before enabling it.

Samples

Sample	Demonstrates
Expense assistant	Application agents and tools in an expense scenario
Product support assistant	Document ingestion and RAG-powered support
Travel planner	Agent workflow orchestration
User-based dashboard security	Dashboard access with user authentication
Role-based dashboard security	Dashboard access with role-based authorization

Each sample guide describes its configuration and run commands.

Build and test

Run these commands from the repository root. PostgreSQL integration tests require Docker with Compose and use the local pgvector service on port 54329.

docker compose -f docker-compose.rag-postgresql.yml up -d --wait
dotnet restore Runiq.AI.slnx
dotnet build Runiq.AI.slnx --no-restore -c Release
dotnet test Runiq.AI.slnx --no-build -c Release --logger trx --results-directory TestResults

When finished with the database:

docker compose -f docker-compose.rag-postgresql.yml stop

The dashboard frontend has separate build and test commands in its development guide.

CI and test reporting

The CI badge reports the main branch workflow status. The .NET tests badge reports executed, passed, failed, and skipped counts from the latest published main run's TRX reports. Skipped tests are excluded from the executed count. Counts are generated by CI, never maintained manually, and exclude the dashboard JavaScript suite.

Click either badge to open GitHub Actions. Each run includes a .NET test results summary and a test-results artifact containing the available TRX reports and badge JSON, including when tests fail. Pull requests produce their own summaries and artifacts; only main push runs update the README badge. The initial badge reads awaiting CI results until CI publishes its first report.

Badge publication requires the workflow token to have repository write access and branch rules to allow the existing bot update. If publication is blocked, the run summary and artifact still contain the results; consult the workflow status for the current run. Shields may briefly cache an older badge.

To verify the reporting script locally with synthetic TRX cases:

pwsh -File scripts/test-update-test-badge.ps1

Create local NuGet packages

After a successful Release build and test run:

dotnet pack Runiq.AI.slnx --no-build -c Release -o artifacts/packages/1.0.0

Package versions are defined in the project files and currently use 1.0.0. This command creates local packages only. Packaging may report NU5104 because Runiq.AI.Rag references the prerelease dependency UglyToad.PdfPig version 1.7.0-custom-5.

Repository layout

Path	Contents
src/Runiq.AI.*	.NET runtime packages and CLI
src/Runiq.Dashboard.Client	Dashboard frontend
samples/	Example applications
tests/	.NET test projects
scripts/	Repository automation and test badge reporting
.github/workflows/	Build, test, and package CI

Contributing and support

Read the contribution guide for local setup and contribution conventions. Use GitHub Issues for reproducible bugs and feature requests, and runiq.net/docs for documentation.

License

Runiq AI is licensed under the MIT License.