Connections and capabilities

A shared connection, two profiles

Maf.DemoConnection provides IChatClient and IEmbeddingGenerator<string, Embedding<float>>. It contains neither agents nor business rules. ChatProvider selects chat; EmbeddingProvider independently selects embeddings. The distributed profile targets Ollama at http://localhost:11434/, granite4:3b for chat and embeddinggemma:300m for vectors. API chat can keep local embeddings.

var builder = Host.CreateApplicationBuilder();
builder.Configuration.AddDemoConfiguration(args);
var settings = ConnectionOptions.FromConfiguration(builder.Configuration);
builder.Services.AddDemoConnection(settings);
using var host = builder.Build();

demos/Demo020_ConnectionProfiles/Console/Program.cs · L7–L11 · 9a895c94534c

Source code · Demo020 · Folder

• demos/Demo020_ConnectionProfiles/Console/Demo020.Console.csproj
• demos/Demo020_ConnectionProfiles/Backend/Demo020.Backend.csproj

Load settings at startup

Priority is: binary-local defaults, central file, environment, explicit demo arguments. The shared file is shared/Configuration/ai-settings.json. Programs find it by walking from their executable toward the solution; the current directory does not select the profile. After saving, restart programs to apply changes without rebuilding. A binary-local copy provides fallback outside the shared tree.

MAF_DEMO_CONFIG selects an existing absolute JSON file. AI__... environment variables use double underscores for sections; --AI:... arguments go after -- in dotnet run. An override can explain why editing the file appears ineffective. Changing chat does not change an embedding index; changing vector provider, model or dimensions requires explicitly rebuilding that index.

public static ConnectionOptions Load(string[] args) => ConnectionOptions.FromConfiguration(
    new ConfigurationBuilder().AddDemoConfiguration(args).Build());

shared/Maf.Backlog/DemoSettings.cs · L10–L11 · 9a895c94534c

Source code · Maf.Backlog · Folder

• shared/Maf.Backlog/Maf.Backlog.csproj
• shared/Maf.DemoConnection/Maf.DemoConnection.csproj

• Central configurator

A chat response does not qualify tools

Creating the client makes no network request. The first request tests the selected service. Demo030 goes further with five probes: text, validated structure, a genuinely executed tool with an unpredictable receipt, streaming and cancellation of an active stream. Its report identifies provider, model, protocol, date and individual results. Failed capabilities stay failed; no alternative provider is tried automatically.

Passed means the probe and its assertions passed on that profile. It proves neither general business understanding nor judge quality. Missing usage counters stay null; do not display them as zero or zero cost. Models can change behind server aliases: retain profiles and test conditions.

• Demo030 — Agent Capabilities

The first agent

Demo040 adapts the client with AsAIAgent, names IntakeAgent and supplies Bug, Feature or Question triage instructions. RunAsync takes a request and returns free text. The console loop does not automatically persist a conversation: it adds no action tool or durable session. Text suggests a priority and component without creating a ticket.

The agent name helps identify it; instructions describe its role. RunAsync returns an AgentResponse, whose Text is a convenient view of final text. Examine messages and tool requests in the full response when the scenario depends on them, as in Demo080.

var agent = chat.AsAIAgent(name: "IntakeAgent", instructions:
    "Classify a product request as Bug, Feature or Question. Suggest priority and component. Answer in English. No actions are available.");

demos/Demo040_FirstAgent/Program.cs · L13–L14 · 9a895c94534c

Source code · Demo040 · Folder

• demos/Demo040_FirstAgent/Demo040.App.csproj

• Demo040 — First Agent

Secrets and deadlines

For an API-compatible profile, explicitly supply endpoint, model and key-variable name. JSON stores the names MAF_API_KEY and MAF_EMBEDDING_API_KEY, never secrets. No ChatGPT account is connected. The distributed HTTP timeout is 120 seconds per request; a token with a deadline bounds the scenario. Demo020 /health availability establishes the HTTP process, not model availability.

Verify, then structure

• Demo020 — Connection Profiles

• Business contracts and validation

Troubleshoot by boundary

• Course resources

• Limits and reservations