.NET API
IAgentSource
Tracon.Abstractions.dllA source the catalog collects agents from. Tracon joins sources declared in code, stored in the database, and registered by the application.
public interface IAgentSourceRemarks
Section titled “Remarks”Sources are singleton instances. Calls can run concurrently, so an implementation must be thread-safe and must not keep request or run state in instance fields. Do not capture scoped services; create a scope from IServiceProvider when needed.
IAgentSource.ListAsync is on the run path, not a startup snapshot API: every successful IAgentSource.ResolveAsync triggers one, and resolving a specific definition version calls it on each source in priority order until the owner is found. It can run repeatedly and must be side-effect free. The catalog does not cache a global snapshot, retry calls, or apply a timeout. A source that needs caching, retries, or a timeout owns that policy — including invalidating its own cache.
IAgentSource.ListAsync and IAgentSource.ResolveAsync describe the same agent set. Returned descriptors and their nested collections must not change after they return.
A source may be global or tenant-aware. Reading ITenantContext is valid. Startup and background calls use the default tenant when no tenant scope is present.
Properties
Section titled “Properties”Gets the name of the source, used for diagnostics and user interface badges.
string Name { get; }Property Value
Section titled “Property Value”Priority
Section titled “ Priority”Gets the resolution priority. A lower value is tried first. When two agents share a name, the source with the lower value wins and the other one is dropped.
int Priority { get; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”AgentSourcePriority.Code and AgentSourcePriority.Database are the values Tracon’s built-in sources use, not reserved values a custom source is barred from choosing. A source that shares one of them simply ties with that built-in source, and DI registration order breaks the tie — the same rule as any other equal-priority pair.
Methods
Section titled “Methods”ListAsync(CancellationToken)
Section titled “ ListAsync(CancellationToken)”Lists every agent in this source.
ValueTask<IReadOnlyList<AgentDescriptor>> ListAsync(CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<IReadOnlyList<AgentDescriptor>>
The agent summaries.
ResolveAsync(string, string?, CancellationToken)
Section titled “ ResolveAsync(string, string?, CancellationToken)”Resolves the agent with the given name and makes it runnable.
ValueTask<AIAgent?> ResolveAsync(string agentName, string? culture = null, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”agentName string
The agent name.
culture string?
The requested culture, resolved against the definition’s culture-keyed instructions
(see AgentDefinition.InstructionsByCulture). null uses the
definition’s default instructions.
cancellationToken CancellationToken
The cancellation token.
Returns
Section titled “Returns”ValueTask<AIAgent?>
The agent, or null when this source does not hold it.