# IAgentCatalog

> 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.iagentcatalog/
> Summary: IAgentCatalog: The catalog that joins every agent source into a single view. The user interface and the HTTP layer reach agents only through this interface.

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

The catalog that joins every agent source into a single view. The user interface
and the HTTP layer reach agents only through this interface.

```csharp
public interface IAgentCatalog
```

## Remarks

Call this interface to look agents up. Tracon supplies the implementation; do not
implement or replace it, because a replacement would have to join every agent source
itself. To add agents, implement [IAgentSource](/api/tracon.iagentsource/) instead.

## Methods

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

Lists the agents from every source. On a name clash the source with the
*lower* [IAgentSource.Priority](/api/tracon.iagentsource/#Tracon_IAgentSource_Priority) value wins - it ranks higher,
because a lower value is tried first - and the other one is not added to the list.

```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/)\>\>

Agent summaries ordered by name.

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

Resolves the agent with the given name. The returned agent is wrapped by the run
recording decorator; every run is written into [IRunStore](/api/tracon.irunstore/).

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

#### 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 no source holds it.

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

Resolves an agent by name and by **a specific definition version**.
Code agents ([AgentDefinitionOrigin.Code](/api/tracon.agentdefinitionorigin/)) have no version history;
[TraconException](/api/tracon.traconexception/) is thrown when `version` is
given for a code agent.

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

#### Parameters

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

The agent name.

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

The requested definition version. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) it behaves like
[IAgentCatalog.ResolveAsync](/api/tracon.iagentcatalog/) (the current version).

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

See [IAgentCatalog.ResolveAsync](/api/tracon.iagentcatalog/).

`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 it is not found.

#### Exceptions

 [TraconException](/api/tracon.traconexception/)

`version` is given and the agent comes from code, or that version
does not exist.