D4S.AgentMetrics 1.0.0

D4S.AgentMetrics

Internal NuGet package for Dev4Side AI agents built on .NET 10.

It handles, transparently:

• Handshake — verifies at startup that the agent is registered and active in the D4S back-end.
• Metric definition registration — sends all metric descriptors (default + custom) to the back-end.
• Business metric tracking — exposes IMetricWriter.TrackAsync with an in-memory queue.
• Periodic flush — drains the queue and POSTs the event batch to the back-end.
• Heartbeat — sends periodic liveness pings to the back-end.

Internal use only. This package is not intended for public distribution.

Prerequisites

The agent must already be registered in the D4S back-end before starting.
Agent creation is handled manually or via the marketplace onboarding process — this package only verifies that the registration exists.
If the agent is missing or inactive the handshake fails and the application will not start.

Installation

dotnet add package D4S.AgentMetrics

Quick start

// Program.cs — minimal required configuration
builder.Services.AddAgentMetrics(options =>
{
    options.AgentId   = "my-agent";
    options.DisplayName = "My Agent";
    options.TenantId  = configuration["Metrics:TenantId"];
    options.BaseUrl   = configuration["Metrics:BaseUrl"];
    options.D4SApiUrl = configuration["Metrics:D4SApiUrl"];
    options.D4SApiKey = configuration["Metrics:D4SApiKey"];
});

// Add the automatic request-tracking middleware
app.UseAgentMetricsTracking();

Configuration

Default profile metrics

These eight metrics are always included automatically — no extra code required.
UseProfile(AgentProfile.Default) is optional but recommended for clarity.

Tracking custom metrics

// Register custom metrics in AddAgentMetrics:
options.AddRanking("top_exams", "Esami più richiesti", dimensionName: "exam_name", topN: 5);
options.AddScalar("avg_confidence_score", "Confidence medio", aggregate: AggregationType.Average);

// Then inject IMetricWriter wherever you need it:
public class MyService
{
    private readonly IMetricWriter _metrics;
    public MyService(IMetricWriter metrics) => _metrics = metrics;

    public async Task HandleAsync(string examName, double confidence)
    {
        // Pure count (value = null)
        await _metrics.TrackAsync("total_interactions");

        // Ranking: increment counter for a dimension value
        await _metrics.TrackAsync("top_exams", dimension: examName);

        // Scalar with a numeric value
        await _metrics.TrackAsync("avg_confidence_score", value: (decimal)confidence);
    }
}

AI token tracking

Wrap your Azure AI Foundry ChatCompletionsClient to record token usage automatically:

// Registration
builder.Services.AddTrackedChatClient(
    new ChatCompletionsClient(endpoint, new AzureKeyCredential(apiKey)),
    model: "gpt-4o");

// Usage — tokens are tracked on every successful call
public class MyAiService
{
    private readonly ITrackedChatClient _ai;
    public MyAiService(ITrackedChatClient ai) => _ai = ai;

    public async Task<string> AnswerAsync(string question)
    {
        var result = await _ai.CompleteAsync(question);
        return result.Choices[0].Message.Content;
    }
}

Development order

For contributors, the recommended implementation sequence is:

1. Models & contracts (MetricType, AggregationType, MetricDescriptor, IMetricWriter, ITrackedChatClient)
2. Configuration (AgentMetricsOptions, AgentProfile)
3. Default profile (DefaultAgentProfile)
4. D4SApiClient — HTTP wrapper for all back-end calls
5. AgentHandshakeService — startup verification
6. MetricWriter — in-memory queue implementation
7. MetricFlushService — periodic flush background service
8. MetricHeartbeatService — periodic heartbeat background service
9. MetricTrackingMiddleware — automatic HTTP request tracking
10. TrackedChatClient — Azure AI Foundry token-usage wrapper
11. ServiceCollectionExtensions — wires everything together

Internal use notice

This package is developed and maintained by Dev4Side for internal use only.
It is not published on NuGet.org and is not intended for external consumption.