Agent Discovery Patterns in FabrCore

Two Scopes by Design

FabrCore provides two distinct APIs for querying agents, each serving a different purpose:

Client-scoped: IClientGrain.GetTrackedAgents() returns agents created by a specific client connection. This represents ownership — which client created which agents.

Global-scoped: The diagnostics API at /fabrcoreapi/diagnostics/agents returns all agents across all users in the cluster. This is an administrative view for monitoring and management.

This separation is intentional. Agents created via the HTTP API don't have a client context, so they aren't tracked by any client grain. HTTP API and client SDK are different entry points with different ownership semantics.

Choosing the Right API

// Get agents owned by this client
var context = await clientContextFactory.GetOrCreateAsync(userHandle);
var tracked = await context.GetTrackedAgents();

// Returns only agents this client created
foreach (var agent in tracked)
{
    logger.LogInformation("Agent: {Handle}", agent.Handle);
}

// Administrative view — all agents in the cluster
GET /fabrcoreapi/diagnostics/agents?status=active

// Aggregate statistics
GET /fabrcoreapi/diagnostics/agents/statistics

When You Need Both

If your application creates agents through both the client SDK and the HTTP API, and you need a unified view, that merge logic belongs in your application code — not the framework. The naming conventions, filtering criteria, and sort order are specific to your application's requirements.

A simple 20-30 line service that queries both APIs and deduplicates by handle is reasonable application code. It's not a framework gap — it's a reflection of your application's specific ownership model.

Learn More

Check out the agent health monitoring documentation for details on querying agent status.