# IExperimentStore

> 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.iexperimentstore/
> Summary: IExperimentStore: Defines the store for A/B experiments.

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

Defines the store for A/B experiments.

```csharp
public interface IExperimentStore
```

## Remarks

**DI lifetime — singleton.** Registered as a singleton with
`TryAdd`; a consumer's own registration wins.

## Methods

### <a id="Tracon_IExperimentStore_AdvanceCanaryRampAsync_System_String_System_String_System_Collections_Generic_IReadOnlyList_Tracon_ExperimentVariant__System_Threading_CancellationToken_"></a> AdvanceCanaryRampAsync\(string, string, IReadOnlyList<ExperimentVariant\>, CancellationToken\)

Applies a gradual-increase decision from the canary evaluator. The
experiment remains [ExperimentStatus.Running](/api/tracon.experimentstatus/) and only variant
weights change. Only the canary evaluation service calls this method.

```csharp
ValueTask<Experiment> AdvanceCanaryRampAsync(string tenantId, string name, IReadOnlyList<ExperimentVariant> variants, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

`variants` [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[ExperimentVariant](/api/tracon.experimentvariant/)\>

The new variant weights. They must total 100.

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

The updated experiment.

### <a id="Tracon_IExperimentStore_DeleteAsync_System_String_System_String_System_Threading_CancellationToken_"></a> DeleteAsync\(string, string, CancellationToken\)

Deletes an experiment. A running experiment must be stopped before deletion.

```csharp
ValueTask<bool> DeleteAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

`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)<[bool](https://learn.microsoft.com/dotnet/api/system.boolean)\>

[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) when deletion occurs.

### <a id="Tracon_IExperimentStore_GetAsync_System_String_System_String_System_Threading_CancellationToken_"></a> GetAsync\(string, string, CancellationToken\)

Gets the experiment with the specified name.

```csharp
ValueTask<Experiment?> GetAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

`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)<[Experiment](/api/tracon.experiment/)?\>

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

### <a id="Tracon_IExperimentStore_GetRunningAsync_System_String_System_String_System_Threading_CancellationToken_"></a> GetRunningAsync\(string, string, CancellationToken\)

Gets the [ExperimentStatus.Running](/api/tracon.experimentstatus/) experiment for an agent.
Returns [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when none exists. An agent can have at most
one running experiment at a time.

```csharp
ValueTask<Experiment?> GetRunningAsync(string tenantId, string agentName, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The agent name.

`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)<[Experiment](/api/tracon.experiment/)?\>

The running experiment, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when none exists.

### <a id="Tracon_IExperimentStore_ListAsync_System_String_System_Threading_CancellationToken_"></a> ListAsync\(string, CancellationToken\)

Lists all experiments for a tenant by name.

```csharp
ValueTask<IReadOnlyList<Experiment>> ListAsync(string tenantId, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiments.

### <a id="Tracon_IExperimentStore_ListRunningWithCanaryAsync_System_Threading_CancellationToken_"></a> ListRunningWithCanaryAsync\(CancellationToken\)

Lists experiments across all tenants that are
[ExperimentStatus.Running](/api/tracon.experimentstatus/) and define [Experiment.Canary](/api/tracon.experiment/#Tracon_Experiment_Canary).

```csharp
ValueTask<IReadOnlyList<Experiment>> ListRunningWithCanaryAsync(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)<[Experiment](/api/tracon.experiment/)\>\>

The running experiments that define a canary policy.

#### Remarks

This is a maintenance operation for the canary evaluator. It scans all
tenants for the same reason as `IPendingApprovalStore.ExpireAsync`.

### <a id="Tracon_IExperimentStore_RollbackCanaryAsync_System_String_System_String_System_Collections_Generic_IReadOnlyList_Tracon_ExperimentVariant__System_String_System_Threading_CancellationToken_"></a> RollbackCanaryAsync\(string, string, IReadOnlyList<ExperimentVariant\>, string, CancellationToken\)

Applies an automatic rollback decision from the canary evaluator. It moves
the experiment to [ExperimentStatus.Stopped](/api/tracon.experimentstatus/), restores weights
to the control variant, and writes [Experiment.RollbackReason](/api/tracon.experiment/#Tracon_Experiment_RollbackReason).

```csharp
ValueTask<Experiment> RollbackCanaryAsync(string tenantId, string name, IReadOnlyList<ExperimentVariant> variants, string reason, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

`variants` [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[ExperimentVariant](/api/tracon.experimentvariant/)\>

The weights restored to the control variant. They must total 100.

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

The rollback reason.

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

The updated experiment.

#### Remarks

The caller, the canary evaluation service, must write
the audit trail before calling this method. If that write fails, it must
not call this method: a rollback that cannot be audited is not applied.

### <a id="Tracon_IExperimentStore_SaveAsync_Tracon_Experiment_System_Threading_CancellationToken_"></a> SaveAsync\(Experiment, CancellationToken\)

Creates or updates an experiment. Only an [ExperimentStatus.Draft](/api/tracon.experimentstatus/)
experiment can be updated. Updating a started experiment throws a
[TraconException](/api/tracon.traconexception/).

```csharp
ValueTask<Experiment> SaveAsync(Experiment experiment, CancellationToken cancellationToken = default)
```

#### Parameters

`experiment` [Experiment](/api/tracon.experiment/)

The experiment to save.

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

The saved experiment.

#### Remarks

This method does not write [Experiment.Canary](/api/tracon.experiment/#Tracon_Experiment_Canary) or
[Experiment.RollbackReason](/api/tracon.experiment/#Tracon_Experiment_RollbackReason): an update keeps the stored values
and a new experiment starts without them, whatever
`experiment` carries. [IExperimentStore.SetCanaryPolicyAsync](/api/tracon.iexperimentstore/#Tracon_IExperimentStore_SetCanaryPolicyAsync_System_String_System_String_Tracon_CanaryPolicy_System_Threading_CancellationToken_)
and the canary evaluator own both, so a draft edit never turns an
automatic rollback off.

### <a id="Tracon_IExperimentStore_SetCanaryPolicyAsync_System_String_System_String_Tracon_CanaryPolicy_System_Threading_CancellationToken_"></a> SetCanaryPolicyAsync\(string, string, CanaryPolicy?, CancellationToken\)

Defines or removes an experiment canary policy. Pass
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for `policy` to remove it.

```csharp
ValueTask<Experiment> SetCanaryPolicyAsync(string tenantId, string name, CanaryPolicy? policy, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

`policy` [CanaryPolicy](/api/tracon.canarypolicy/)?

The new policy, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) to remove it.

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

The updated experiment.

#### Remarks

Unlike [IExperimentStore.SaveAsync](/api/tracon.iexperimentstore/#Tracon_IExperimentStore_SaveAsync_Tracon_Experiment_System_Threading_CancellationToken_), this method works regardless of experiment
status, Draft or Running. A canary policy can be defined while an experiment
already receives traffic.

### <a id="Tracon_IExperimentStore_StartAsync_System_String_System_String_System_Threading_CancellationToken_"></a> StartAsync\(string, string, CancellationToken\)

Moves the experiment to [ExperimentStatus.Running](/api/tracon.experimentstatus/). Throws a
[TraconException](/api/tracon.traconexception/) when another experiment runs for the same agent.

```csharp
ValueTask<Experiment> StartAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

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

The updated experiment.

### <a id="Tracon_IExperimentStore_StopAsync_System_String_System_String_System_Threading_CancellationToken_"></a> StopAsync\(string, string, CancellationToken\)

Moves the experiment to [ExperimentStatus.Stopped](/api/tracon.experimentstatus/).

```csharp
ValueTask<Experiment> StopAsync(string tenantId, string name, CancellationToken cancellationToken = default)
```

#### Parameters

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

The tenant identifier.

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

The experiment name.

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

The updated experiment.