# ILiveVoiceProvider

> 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.ilivevoiceprovider/
> Summary: ILiveVoiceProvider: Creates and supervises a provider-hosted live voice session.

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

Creates and supervises a provider-hosted live voice session.

```csharp
public interface ILiveVoiceProvider
```

## Remarks

A live session is **not** the conversation layer behind
`UseVoiceConversation`. There, Tracon receives the audio, transcribes
it, runs the agent and synthesizes the answer. Here the provider hosts the whole
conversation and carries the media directly to the media peer; Tracon stands
in two places only: it *creates* the session, so tenancy, role and
concurrency gates apply and the raw API key never reaches the browser, and it
*attaches* a server-side control connection, so the work the model
delegates becomes an ordinary Tracon run.

**Lifetime:** registered `singleton`. One instance serves every
session in the process, so an implementation must be thread-safe and must hold no
per-session state of its own — [ILiveVoiceSideband](/api/tracon.ilivevoicesideband/) is where a
session's state lives.

**Tenant:** `tenant-independent`, like
[ISpeechSynthesizer](/api/tracon.ispeechsynthesizer/). The caller has already resolved and gated the
tenant before a session is created: Tracon applies the tenant's egress policy to
[ILiveVoiceProvider.ProviderName](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_ProviderName) and resolves the tenant's own credential from its
provider binding, exactly as for a model call. The provider neither reads nor
enforces a tenant, and must not key any cache or credential by tenant; a
tenant credential reaches it only through the request
([LiveVoiceCreateRequest.Credential](/api/tracon.livevoicecreaterequest/#Tracon_LiveVoiceCreateRequest_Credential),
[LiveVoiceAttachRequest.Credential](/api/tracon.livevoiceattachrequest/#Tracon_LiveVoiceAttachRequest_Credential)), and only when
[ILiveVoiceProvider.SupportsTenantCredentials](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_SupportsTenantCredentials) is [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

**Delivery:** `best-effort`. Creating a session and attaching to
it are ordinary network calls with no retry and no idempotency key: a failure is
surfaced to the caller, never retried silently, because a retried create is a
second billed session.

## Properties

### <a id="Tracon_ILiveVoiceProvider_MaxAppendCharacters"></a> MaxAppendCharacters

Gets the largest number of characters a single
[ILiveVoiceSideband.AppendAsync](/api/tracon.ilivevoicesideband/#Tracon_ILiveVoiceSideband_AppendAsync_Tracon_LiveVoiceAppend_System_Threading_CancellationToken_) may carry.

```csharp
int MaxAppendCharacters { get; }
```

#### Property Value

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

#### Remarks

The ceiling is in **characters**, not tokens: Tracon ships no
tokenizer and must not take one on (AOT, and no new package). An implementation
whose provider states the limit in tokens converts it once, conservatively, and
documents the ratio in a single place.

### <a id="Tracon_ILiveVoiceProvider_ModelId"></a> ModelId

Gets the model identifier written to the session record.

```csharp
string ModelId { get; }
```

#### Property Value

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

### <a id="Tracon_ILiveVoiceProvider_ProviderName"></a> ProviderName

Gets the provider name written to the session record, e.g. `openai`.

```csharp
string ProviderName { get; }
```

#### Property Value

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

### <a id="Tracon_ILiveVoiceProvider_SupportsTenantCredentials"></a> SupportsTenantCredentials

Gets whether the provider honours a tenant credential passed in
[LiveVoiceCreateRequest.Credential](/api/tracon.livevoicecreaterequest/#Tracon_LiveVoiceCreateRequest_Credential) and
[LiveVoiceAttachRequest.Credential](/api/tracon.livevoiceattachrequest/#Tracon_LiveVoiceAttachRequest_Credential).

```csharp
bool SupportsTenantCredentials { get; }
```

#### Property Value

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

#### Remarks

The default is [false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool). Tracon then refuses a session for a
tenant that has its own binding for [ILiveVoiceProvider.ProviderName](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_ProviderName) rather than
open it on the provider's configured credential, which would bill the wrong
account. An implementation that returns [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) uses the
credential for both calls of the session and never falls back to its
configured one.

## Methods

### <a id="Tracon_ILiveVoiceProvider_AttachAsync_System_String_System_Threading_CancellationToken_"></a> AttachAsync\(string, CancellationToken\)

Opens a server-side control connection to an existing session.

```csharp
ValueTask<ILiveVoiceSideband> AttachAsync(string providerSessionId, CancellationToken cancellationToken = default)
```

#### Parameters

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

The identifier returned by [ILiveVoiceProvider.CreateSessionAsync](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_CreateSessionAsync_Tracon_LiveVoiceCreateRequest_System_Threading_CancellationToken_).

`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)<[ILiveVoiceSideband](/api/tracon.ilivevoicesideband/)\>

The sideband connection.

#### Remarks

The connection carries **no** primary audio: WebRTC or SIP carries
that. Both connections share one session.

### <a id="Tracon_ILiveVoiceProvider_AttachSessionAsync_Tracon_LiveVoiceAttachRequest_System_Threading_CancellationToken_"></a> AttachSessionAsync\(LiveVoiceAttachRequest, CancellationToken\)

Opens a server-side control connection to an existing session.

```csharp
ValueTask<ILiveVoiceSideband> AttachSessionAsync(LiveVoiceAttachRequest request, CancellationToken cancellationToken = default)
```

#### Parameters

`request` [LiveVoiceAttachRequest](/api/tracon.livevoiceattachrequest/)

The provider's session identifier and the credential to connect with.

`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)<[ILiveVoiceSideband](/api/tracon.ilivevoicesideband/)\>

The sideband connection.

#### Remarks

The default implementation calls [ILiveVoiceProvider.AttachAsync](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_AttachAsync_System_String_System_Threading_CancellationToken_)
when no credential is given and throws [NotSupportedException](https://learn.microsoft.com/dotnet/api/system.notsupportedexception) when
one is: an implementation that cannot use the tenant's credential must not
connect with its own instead. Tracon calls this method, the pair of
[ILiveVoiceProvider.CreateSessionAsync](/api/tracon.ilivevoiceprovider/#Tracon_ILiveVoiceProvider_CreateSessionAsync_Tracon_LiveVoiceCreateRequest_System_Threading_CancellationToken_).

#### Exceptions

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

[LiveVoiceAttachRequest.Credential](/api/tracon.livevoiceattachrequest/#Tracon_LiveVoiceAttachRequest_Credential) is set and the implementation does
not override this method.

### <a id="Tracon_ILiveVoiceProvider_CreateSessionAsync_Tracon_LiveVoiceCreateRequest_System_Threading_CancellationToken_"></a> CreateSessionAsync\(LiveVoiceCreateRequest, CancellationToken\)

Relays the media peer's SDP offer and creates the session.

```csharp
ValueTask<LiveVoiceSessionHandle> CreateSessionAsync(LiveVoiceCreateRequest request, CancellationToken cancellationToken = default)
```

#### Parameters

`request` [LiveVoiceCreateRequest](/api/tracon.livevoicecreaterequest/)

The offer and the session settings.

`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)<[LiveVoiceSessionHandle](/api/tracon.livevoicesessionhandle/)\>

The provider's session identifier and its SDP answer.