# IAgentSource

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.iagentsource/
> Summary: IAgentSource: A source the catalog collects agents from. Tracon joins sources declared in code, stored in the database, and registered by the application.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

A source the catalog collects agents from. Tracon joins sources declared in
code, stored in the database, and registered by the application.

```csharp
public interface IAgentSource
```

## 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](https://learn.microsoft.com/dotnet/api/system.iserviceprovider) when needed.

[IAgentSource.ListAsync](/api/tracon.iagentsource/#Tracon_IAgentSource_ListAsync_System_Threading_CancellationToken_) is on the run path, not a startup snapshot API: every
successful [IAgentSource.ResolveAsync](/api/tracon.iagentsource/#Tracon_IAgentSource_ResolveAsync_System_String_System_String_System_Threading_CancellationToken_) 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](/api/tracon.iagentsource/#Tracon_IAgentSource_ListAsync_System_Threading_CancellationToken_) and [IAgentSource.ResolveAsync](/api/tracon.iagentsource/#Tracon_IAgentSource_ResolveAsync_System_String_System_String_System_Threading_CancellationToken_) 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](/api/tracon.itenantcontext/) is valid.
Startup and background calls use the default tenant when no tenant scope is present.

## Properties

### <a id="Tracon_IAgentSource_Name"></a> Name

Gets the name of the source, used for diagnostics and user interface badges.

```csharp
string Name { get; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)

### <a id="Tracon_IAgentSource_Priority"></a> 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.

```csharp
int Priority { get; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

[AgentSourcePriority.Code](/api/tracon.agentsourcepriority/#Tracon_AgentSourcePriority_Code) and [AgentSourcePriority.Database](/api/tracon.agentsourcepriority/#Tracon_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

### <a id="Tracon_IAgentSource_ListAsync_System_Threading_CancellationToken_"></a> ListAsync\(CancellationToken\)

Lists every agent in this source.

```csharp
ValueTask<IReadOnlyList<AgentDescriptor>> ListAsync(CancellationToken cancellationToken = default)
```

#### Parameters

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<[IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[AgentDescriptor](/api/tracon.agentdescriptor/)\>\>

The agent summaries.

### <a id="Tracon_IAgentSource_ResolveAsync_System_String_System_String_System_Threading_CancellationToken_"></a> ResolveAsync\(string, string?, CancellationToken\)

Resolves the agent with the given name and makes it runnable.

```csharp
ValueTask<AIAgent?> ResolveAsync(string agentName, string? culture = null, CancellationToken cancellationToken = default)
```

#### Parameters

`agentName` [string](https://learn.microsoft.com/dotnet/api/system.string)

The agent name.

`culture` [string](https://learn.microsoft.com/dotnet/api/system.string)?

The requested culture, resolved against the definition's culture-keyed instructions
(see `AgentDefinition.InstructionsByCulture`). [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) uses the
definition's default instructions.

`cancellationToken` [CancellationToken](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken)

The cancellation token.

#### Returns

 [ValueTask](https://learn.microsoft.com/dotnet/api/system.threading.tasks.valuetask\-1)<AIAgent?\>

The agent, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when this source does not hold it.