# ModelBinding

> 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.modelbinding/
> Summary: ModelBinding: Determines the provider and the model an agent runs with. It carries no credentials; the API key is resolved from configuration.

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

Determines the provider and the model an agent runs with. It carries
*no* credentials; the API key is resolved from configuration.

```csharp
public sealed record ModelBinding : IEquatable<ModelBinding>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.modelbinding/">ModelBinding</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;ModelBinding&gt;</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Constructors

### <a id="Tracon_ModelBinding__ctor"></a> ModelBinding\(\)

```csharp
public ModelBinding()
```

## Properties

### <a id="Tracon_ModelBinding_AllowMultipleToolCalls"></a> AllowMultipleToolCalls

Gets whether the model may ask for several tool calls in one turn. The provider default
is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public bool? AllowMultipleToolCalls { get; init; }
```

#### Property Value

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

#### Remarks

It is not [ToolLoopSettings.AllowConcurrentToolCalls](/api/tracon.toolloopsettings/#Tracon_ToolLoopSettings_AllowConcurrentToolCalls): this one controls
what the model may ask for, that one controls whether Tracon runs the calls at the
same time.

### <a id="Tracon_ModelBinding_Fallbacks"></a> Fallbacks

Gets the ordered fallback chain tried when the primary provider is
unavailable. Empty by default.

```csharp
public IReadOnlyList<ModelFallback> Fallbacks { get; init; }
```

#### Property Value

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

#### Remarks

Empty by default: with no fallback configured, today's behavior is
preserved exactly — a provider failure (for example an open circuit)
still throws, and no fallback code path runs.

A fallback link carries only a provider and a model, not a full
[ModelBinding](/api/tracon.modelbinding/). The fallback call receives the primary call's
request options — [ModelBinding.Temperature](/api/tracon.modelbinding/#Tracon_ModelBinding_Temperature), [ModelBinding.TopP](/api/tracon.modelbinding/#Tracon_ModelBinding_TopP),
[ModelBinding.MaxOutputTokens](/api/tracon.modelbinding/#Tracon_ModelBinding_MaxOutputTokens), [ModelBinding.ResponseFormat](/api/tracon.modelbinding/#Tracon_ModelBinding_ResponseFormat), the other sampling
fields ([ModelBinding.Seed](/api/tracon.modelbinding/#Tracon_ModelBinding_Seed), [ModelBinding.TopK](/api/tracon.modelbinding/#Tracon_ModelBinding_TopK), [ModelBinding.StopSequences](/api/tracon.modelbinding/#Tracon_ModelBinding_StopSequences), the penalties,
[ModelBinding.ToolMode](/api/tracon.modelbinding/#Tracon_ModelBinding_ToolMode), [ModelBinding.AllowMultipleToolCalls](/api/tracon.modelbinding/#Tracon_ModelBinding_AllowMultipleToolCalls), [ModelBinding.ReasoningOutput](/api/tracon.modelbinding/#Tracon_ModelBinding_ReasoningOutput))
and the tools — with only the model name replaced; the link also takes
[ModelBinding.ToolLoop](/api/tracon.modelbinding/#Tracon_ModelBinding_ToolLoop) as one object. [ModelBinding.ProviderSettings](/api/tracon.modelbinding/#Tracon_ModelBinding_ProviderSettings) do not
carry over: they configure the primary provider's client. A fallback model
that needs its own settings is a separate configuration concern, not something
this chain expresses.

Switching to a fallback is never silent: the run record gets an
explicit `ModelFallbackUsed` event, and cost and model attribution
(`RunStatistics.ByModel`) reflect the model that actually answered,
not the primary binding.

That applies to the agent's own binding. A binding the run calls on the
side, such as the context compaction summarizer or the judge of an
`aiJudge` loop criterion, keeps its fallback to that call: the run
keeps the agent's model and gets no event, the call's tokens are priced
at the model that answered, and the switch is logged.

### <a id="Tracon_ModelBinding_FrequencyPenalty"></a> FrequencyPenalty

Gets the frequency penalty. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public float? FrequencyPenalty { get; init; }
```

#### Property Value

 [float](https://learn.microsoft.com/dotnet/api/system.single)?

### <a id="Tracon_ModelBinding_MaxOutputTokens"></a> MaxOutputTokens

Gets the upper output token limit. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public int? MaxOutputTokens { get; init; }
```

#### Property Value

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

### <a id="Tracon_ModelBinding_Model"></a> Model

Gets the model name, for example `gpt-5.4-mini`.

```csharp
public required string Model { get; init; }
```

#### Property Value

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

### <a id="Tracon_ModelBinding_PresencePenalty"></a> PresencePenalty

Gets the presence penalty. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public float? PresencePenalty { get; init; }
```

#### Property Value

 [float](https://learn.microsoft.com/dotnet/api/system.single)?

### <a id="Tracon_ModelBinding_Provider"></a> Provider

Gets the provider name, for example `openai`.

```csharp
public required string Provider { get; init; }
```

#### Property Value

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

### <a id="Tracon_ModelBinding_ProviderSettings"></a> ProviderSettings

Gets the provider-specific extra settings. A key has the form `{provider}.{setting}`.

```csharp
public IReadOnlyDictionary<string, JsonElement> ProviderSettings { get; init; }
```

#### Property Value

 [IReadOnlyDictionary](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlydictionary\-2)<[string](https://learn.microsoft.com/dotnet/api/system.string), [JsonElement](https://learn.microsoft.com/dotnet/api/system.text.json.jsonelement)\>

#### Remarks

The prompt caching of Anthropic or the safety thresholds of Gemini do not fit the
fixed fields of this contract. Adding them to the body of [ModelBinding](/api/tracon.modelbinding/)
would leak one vendor's concept into `Tracon.Abstractions`. This dictionary
keeps the contract clean: each provider reads only its own prefix.

**An unknown key is not ignored silently.** When a provider sees a key
it does not recognize, the build fails and lists the keys it supports. The reason
is the same as for [ModelBinding.ReasoningEffort](/api/tracon.modelbinding/#Tracon_ModelBinding_ReasoningEffort): a setting that is
ignored silently makes the user miss the behaviour they expect without seeing why.

Keys are compared with `StringComparer.OrdinalIgnoreCase`. Use the
[ModelProviderSettings](/api/tracon.modelprovidersettings/) helpers to read them.

```json
"ProviderSettings": {
  "anthropic.promptCaching": true,
  "anthropic.thinking.budgetTokens": 8000,
  "google.safety.harassment": "BLOCK_ONLY_HIGH"
}
```

### <a id="Tracon_ModelBinding_ReasoningEffort"></a> ReasoningEffort

Gets the reasoning effort level. Models that support it use the value; the other
providers ignore it.

```csharp
public string? ReasoningEffort { get; init; }
```

#### Property Value

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

#### Remarks

The valid values are the `Microsoft.Extensions.AI.ReasoningEffort` names:
`None`, `Low`, `Medium`, `High`, `ExtraHigh`. The
comparison is case insensitive. An unrecognized value is rejected while the agent
is built, with `TraconCompilationException`; it is not ignored silently.

### <a id="Tracon_ModelBinding_ReasoningOutput"></a> ReasoningOutput

Gets how much of the model's reasoning the response carries. The provider default is
used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public string? ReasoningOutput { get; init; }
```

#### Property Value

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

#### Remarks

The valid values are the `Microsoft.Extensions.AI.ReasoningOutput` names:
`None`, `Summary`, `Full`. The comparison is case insensitive. An
unrecognized value is rejected while the agent is built, with
`TraconCompilationException`, in the same way as [ModelBinding.ReasoningEffort](/api/tracon.modelbinding/#Tracon_ModelBinding_ReasoningEffort).

### <a id="Tracon_ModelBinding_ResponseCache"></a> ResponseCache

Gets the response caching settings. Disabled when [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public ResponseCacheSettings? ResponseCache { get; init; }
```

#### Property Value

 [ResponseCacheSettings](/api/tracon.responsecachesettings/)?

#### Remarks

Disabled by default: with no cache configured, today's behavior is
preserved exactly — every call reaches the model, and no cache ring is
added to the pipeline.

Enabling it while no `IDistributedCache` is registered is not
silently ignored: compilation stops with
`TraconCompilationException`, naming the missing registration.

### <a id="Tracon_ModelBinding_ResponseFormat"></a> ResponseFormat

Gets the requested output format. When it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) today's
behaviour does not change: no format constraint is sent to the provider.

```csharp
public AgentResponseFormat? ResponseFormat { get; init; }
```

#### Property Value

 [AgentResponseFormat](/api/tracon.agentresponseformat/)?

#### Remarks

[AgentResponseFormatKind.Text](/api/tracon.agentresponseformatkind/) differs from [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null):
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) means "say nothing", `Text` means "ask for plain text
explicitly". An invalid combination (for example
[AgentResponseFormatKind.JsonSchema](/api/tracon.agentresponseformatkind/) without a schema) is rejected
while the agent is built, with `TraconCompilationException`.

### <a id="Tracon_ModelBinding_Seed"></a> Seed

Gets the sampling seed. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public long? Seed { get; init; }
```

#### Property Value

 [long](https://learn.microsoft.com/dotnet/api/system.int64)?

#### Remarks

Sent only by the API surfaces that support it (see [ISamplingSupport](/api/tracon.isamplingsupport/)); a
definition that sets it for a provider that does not is rejected while the agent is
built. The same holds for [ModelBinding.TopK](/api/tracon.modelbinding/#Tracon_ModelBinding_TopK), [ModelBinding.StopSequences](/api/tracon.modelbinding/#Tracon_ModelBinding_StopSequences),
[ModelBinding.FrequencyPenalty](/api/tracon.modelbinding/#Tracon_ModelBinding_FrequencyPenalty), [ModelBinding.PresencePenalty](/api/tracon.modelbinding/#Tracon_ModelBinding_PresencePenalty), [ModelBinding.ToolMode](/api/tracon.modelbinding/#Tracon_ModelBinding_ToolMode),
[ModelBinding.AllowMultipleToolCalls](/api/tracon.modelbinding/#Tracon_ModelBinding_AllowMultipleToolCalls) and [ModelBinding.ReasoningOutput](/api/tracon.modelbinding/#Tracon_ModelBinding_ReasoningOutput), on the primary
provider and on every [ModelBinding.Fallbacks](/api/tracon.modelbinding/#Tracon_ModelBinding_Fallbacks) link.

### <a id="Tracon_ModelBinding_StopSequences"></a> StopSequences

Gets the sequences that stop generation. Nothing is sent when it is
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) or empty.

```csharp
public IReadOnlyList<string>? StopSequences { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[string](https://learn.microsoft.com/dotnet/api/system.string)\>?

#### Remarks

An entry must not be empty. The providers limit how many sequences a request may carry;
the provider's own error is returned when the limit is exceeded.

### <a id="Tracon_ModelBinding_Temperature"></a> Temperature

Gets the sampling temperature. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public float? Temperature { get; init; }
```

#### Property Value

 [float](https://learn.microsoft.com/dotnet/api/system.single)?

### <a id="Tracon_ModelBinding_ToolLoop"></a> ToolLoop

Gets the settings of the tool-call loop the model pipeline builds.

```csharp
public ToolLoopSettings ToolLoop { get; init; }
```

#### Property Value

 [ToolLoopSettings](/api/tracon.toolloopsettings/)

#### Remarks

The defaults keep today's behavior: the loop runs tool calls one after another and uses
its own limits. A fallback link takes this object as it is.

It is never [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when read, and it accepts [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when set:
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) becomes the default settings, so a client that sends
`"toolLoop": null` is not refused. A source-generated JSON reader assigns
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) to a member that is absent from the JSON when the type has
[required](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/required) members (measured), which is what a definition stored before this
member existed looks like.

### <a id="Tracon_ModelBinding_ToolMode"></a> ToolMode

Gets how the model may use the agent's tools. The provider default (the model decides)
is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public string? ToolMode { get; init; }
```

#### Property Value

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

#### Remarks

The values are `auto`, `none`, `required` (the model must call a tool)
and `required:<tool>` (the model must call that tool). The comparison is case
insensitive. The tool in `required:<tool>` must be one of the definition's
[AgentDefinition.ToolNames](/api/tracon.agentdefinition/#Tracon_AgentDefinition_ToolNames). An unrecognized value is rejected while the
agent is built, with `TraconCompilationException`.

`required` and `required:<tool>` force the first model call of a turn
only: the tool-call loop lifts the requirement for the calls that follow, or the model
could never answer.

### <a id="Tracon_ModelBinding_TopK"></a> TopK

Gets the top-k sampling limit. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public int? TopK { get; init; }
```

#### Property Value

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

#### Remarks

It must be greater than zero.

### <a id="Tracon_ModelBinding_TopP"></a> TopP

Gets the nucleus sampling threshold. The provider default is used when it is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public float? TopP { get; init; }
```

#### Property Value

 [float](https://learn.microsoft.com/dotnet/api/system.single)?

## Methods

### <a id="Tracon_ModelBinding_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

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

#### Returns

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

### <a id="Tracon_ModelBinding_Equals_Tracon_ModelBinding_"></a> Equals\(ModelBinding?\)

```csharp
public bool Equals(ModelBinding? other)
```

#### Parameters

`other` [ModelBinding](/api/tracon.modelbinding/)?

#### Returns

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

### <a id="Tracon_ModelBinding_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

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

### <a id="Tracon_ModelBinding_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

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

## Operators

### <a id="Tracon_ModelBinding_op_Equality_Tracon_ModelBinding_Tracon_ModelBinding_"></a> operator ==\(ModelBinding?, ModelBinding?\)

```csharp
public static bool operator ==(ModelBinding? left, ModelBinding? right)
```

#### Parameters

`left` [ModelBinding](/api/tracon.modelbinding/)?

`right` [ModelBinding](/api/tracon.modelbinding/)?

#### Returns

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

### <a id="Tracon_ModelBinding_op_Inequality_Tracon_ModelBinding_Tracon_ModelBinding_"></a> operator \!=\(ModelBinding?, ModelBinding?\)

```csharp
public static bool operator !=(ModelBinding? left, ModelBinding? right)
```

#### Parameters

`left` [ModelBinding](/api/tracon.modelbinding/)?

`right` [ModelBinding](/api/tracon.modelbinding/)?

#### Returns

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