# AgentDefinition

> 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.agentdefinition/
> Summary: AgentDefinition: The full definition of an agent. The same type is used whether the agent is declared in code or stored in the database; AgentDefinition.Origin tells the two apart.

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

The full definition of an agent. The same type is used whether the agent is
declared in code or stored in the database; [AgentDefinition.Origin](/api/tracon.agentdefinition/#Tracon_AgentDefinition_Origin) tells the two apart.

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

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.agentdefinition/">AgentDefinition</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;AgentDefinition&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>

## Remarks

[AgentDefinition.ToolNames](/api/tracon.agentdefinition/#Tracon_AgentDefinition_ToolNames) is a list of *names* only, never code. A definition
can point only at a tool registered in `IToolRegistry` in code. This is one of
the security boundaries of Tracon: the user interface can create an agent, but
it cannot define executable code.

A definition never carries credentials such as an API key. Provider credentials come
from configuration and are not written to the database.

A collection member is never [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null). A serializer that builds the record
without running its initializers (a source-generated context reading a file that leaves
the member out, or writes `null` for it) still reads an empty collection, so a source
that reads definitions from JSON does not restore the members itself.

## Constructors

### <a id="Tracon_AgentDefinition__ctor"></a> AgentDefinition\(\)

```csharp
public AgentDefinition()
```

## Properties

### <a id="Tracon_AgentDefinition_CallableAgents"></a> CallableAgents

Gets the other agents this agent may call, each with the version of it that runs.

```csharp
public IReadOnlyList<CallableAgentReference> CallableAgents { get; init; }
```

#### Property Value

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

#### Remarks

Every name must resolve to an agent in the catalog. The call graph is checked
**when the definition is saved**: self calls and indirect cycles
are rejected.

A reference with no [CallableAgentReference.Version](/api/tracon.callableagentreference/#Tracon_CallableAgentReference_Version) runs the callee's current version.
One with a version runs that stored version, and for an agent kept in the database its description comes from that version. The version
must exist and the callee must keep a version history (an agent defined in code does not), or the
definition is refused when it is saved and when it is compiled. A name appears once.

The static check alone is not enough - a factory agent on the code side carries
no graph. A depth counter therefore also runs at run time
([AgentRunBudget.MaxDepth](/api/tracon.agentrunbudget/#Tracon_AgentRunBudget_MaxDepth)).

A child agent runs in the **same tenant** and cannot change the tenant.

### <a id="Tracon_AgentDefinition_Compaction"></a> Compaction

Gets the context compaction settings. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) no compaction
is applied.

```csharp
public CompactionSettings? Compaction { get; init; }
```

#### Property Value

 [CompactionSettings](/api/tracon.compactionsettings/)?

### <a id="Tracon_AgentDefinition_Description"></a> Description

Gets a short description of what the agent does.

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

#### Property Value

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

### <a id="Tracon_AgentDefinition_DisplayName"></a> DisplayName

Gets the name shown in the user interface. `Name` is used when it is empty.

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

#### Property Value

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

### <a id="Tracon_AgentDefinition_ExtensionNames"></a> ExtensionNames

Gets the names of the agent extensions this agent is compiled with, in call
order. Every name must match an extension registered in code with
`AddAgentExtension`; otherwise building the agent fails.

```csharp
public IReadOnlyList<string> ExtensionNames { 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

A list of *names* only, never code - the same boundary as
[AgentDefinition.ToolNames](/api/tracon.agentdefinition/#Tracon_AgentDefinition_ToolNames). An extension reaches the Microsoft Agent Framework
options the compiler builds for this agent; it cannot change the members the
definition or Tracon's tenant and security decisions own.

### <a id="Tracon_AgentDefinition_Harness"></a> Harness

Gets the harness settings. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) a plain chat agent is
produced; when populated, harness capabilities such as context compaction and
todo tracking are enabled.

```csharp
public HarnessSettings? Harness { get; init; }
```

#### Property Value

 [HarnessSettings](/api/tracon.harnesssettings/)?

### <a id="Tracon_AgentDefinition_Instructions"></a> Instructions

Gets the system instructions passed to the model.

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

#### Property Value

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

### <a id="Tracon_AgentDefinition_InstructionsByCulture"></a> InstructionsByCulture

Gets culture-keyed instructions. The key is a BCP-47 tag (`"en"`, `"tr"`);
a region subtag (`"tr-TR"`) falls back to its parent (`"tr"`). A run's
requested culture that matches neither falls back to `Instructions` -
resolution never fails.

```csharp
public IReadOnlyDictionary<string, string>? InstructionsByCulture { 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), [string](https://learn.microsoft.com/dotnet/api/system.string)\>?

### <a id="Tracon_AgentDefinition_McpResourceUris"></a> McpResourceUris

Gets the MCP resources added to the run context (mode A). Each item has the
form `"{server}:{uri}"`. They are read at the start of the run and are
predictable; every run receives the same resources.

```csharp
public IReadOnlyList<string> McpResourceUris { 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

Reading resources requires the `Tracon.Mcp` package to be registered
(`UseMcp`); otherwise building the agent fails. A size limit applies:
64 KB per resource, 256 KB in total.

### <a id="Tracon_AgentDefinition_Memory"></a> Memory

Gets the memory provider settings. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) no memory provider
is added.

```csharp
public MemorySettings? Memory { get; init; }
```

#### Property Value

 [MemorySettings](/api/tracon.memorysettings/)?

### <a id="Tracon_AgentDefinition_Metadata"></a> Metadata

Gets free-form, application-specific metadata.

```csharp
public IReadOnlyDictionary<string, JsonElement> Metadata { 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)\>

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

Gets the provider and model binding to use.

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

#### Property Value

 [ModelBinding](/api/tracon.modelbinding/)

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

Gets the unique name of the agent, used as the key in the catalog and in API routes.

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

#### Property Value

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

### <a id="Tracon_AgentDefinition_Origin"></a> Origin

Gets the origin of the definition: code or database.

```csharp
public AgentDefinitionOrigin Origin { get; init; }
```

#### Property Value

 [AgentDefinitionOrigin](/api/tracon.agentdefinitionorigin/)

### <a id="Tracon_AgentDefinition_Parameters"></a> Parameters

Gets the schema of named placeholders (`{{name}}`) this definition's
instructions may reference.

```csharp
public IReadOnlyList<AgentParameter> Parameters { get; init; }
```

#### Property Value

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

#### Remarks

Validated at compile time: see [AgentParameter](/api/tracon.agentparameter/). A run
supplies concrete values through `AgentRunRequest.Parameters`; the
definition itself carries only the schema, never a value.

### <a id="Tracon_AgentDefinition_SharedInstructionsName"></a> SharedInstructionsName

Gets the name of another definition whose `Instructions` text is
prepended to this definition's own resolved instructions at compile time.

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

#### Property Value

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

#### Remarks

A shared instructions block is an ordinary [AgentDefinition](/api/tracon.agentdefinition/) -
there is no separate type or table for it. It gets versioning, tenancy,
and the audit trail for free because it is saved through the same
`IAgentDefinitionStore`.

The reference cannot be recursive: a definition whose own
`SharedInstructionsName` is set cannot be referenced by
another definition. This is checked at compile time and rejected
outright rather than resolved through a cycle-detecting walk - a single
disallowed hop is enough for the "shared block" use case and keeps the
feature far from being a template engine.

### <a id="Tracon_AgentDefinition_SkillNames"></a> SkillNames

Gets the names of the skills this agent may load at run time. Every name must
match an enabled skill found in code or in the skill store.

```csharp
public IReadOnlyList<string> SkillNames { 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)\>

### <a id="Tracon_AgentDefinition_Skills"></a> Skills

Gets how this agent uses its skills. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), all three skill
tools ask for approval. Ignored when `SkillNames` is empty.

```csharp
public SkillSettings? Skills { get; init; }
```

#### Property Value

 [SkillSettings](/api/tracon.skillsettings/)?

#### Remarks

An agent exposed over A2A or MCP must turn the read approval off, or the host
refuses to expose it. See [SkillSettings.DisableReadApproval](/api/tracon.skillsettings/#Tracon_SkillSettings_DisableReadApproval).

### <a id="Tracon_AgentDefinition_SubAgents"></a> SubAgents

Gets how this agent calls the agents it may call
(`SubAgentSettings.CallMode`) and how long it waits for them. When
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null), the agent uses background tasks and
`TraconAgentGraphOptions.ChildDeadline` and `WaitTimeout` apply.
Ignored when `CallableAgents` is empty.

```csharp
public SubAgentSettings? SubAgents { get; init; }
```

#### Property Value

 [SubAgentSettings](/api/tracon.subagentsettings/)?

### <a id="Tracon_AgentDefinition_TenantId"></a> TenantId

Gets the tenant this definition belongs to. A single-tenant setup uses the default value.

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

#### Property Value

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

### <a id="Tracon_AgentDefinition_ToolNames"></a> ToolNames

Gets the names of the tools this agent may use. Every name must match a tool
registered in code; otherwise building the agent fails.

```csharp
public IReadOnlyList<string> ToolNames { 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)\>

### <a id="Tracon_AgentDefinition_UpdatedAt"></a> UpdatedAt

Gets the time the definition last changed (UTC).

```csharp
public DateTimeOffset? UpdatedAt { get; init; }
```

#### Property Value

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

### <a id="Tracon_AgentDefinition_Version"></a> Version

Gets the definition version. Every save increments it, and the store owns the
number: the value on an incoming definition is ignored.

```csharp
public int Version { get; init; }
```

#### Property Value

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

#### Remarks

The version is a history marker, not an identity. Deleting a definition and
creating one with the same name starts the numbering again at `1`, so two
different definitions can carry the same name and the same version. Anything
that needs to tell one definition's content from another's must compare the
content itself; the compiled agent cache does exactly that.

### <a id="Tracon_AgentDefinition_Workspace"></a> Workspace

Gets the session workspace settings. When [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) the agent has no workspace.

```csharp
public WorkspaceSettings? Workspace { get; init; }
```

#### Property Value

 [WorkspaceSettings](/api/tracon.workspacesettings/)?

#### Remarks

An agent exposed over A2A or MCP must make its workspace read-only and turn the read approval
off, or the host refuses to expose it. See [WorkspaceSettings](/api/tracon.workspacesettings/).

## Methods

### <a id="Tracon_AgentDefinition_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_AgentDefinition_Equals_Tracon_AgentDefinition_"></a> Equals\(AgentDefinition?\)

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

#### Parameters

`other` [AgentDefinition](/api/tracon.agentdefinition/)?

#### Returns

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

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

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

#### Returns

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

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

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

#### Returns

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

## Operators

### <a id="Tracon_AgentDefinition_op_Equality_Tracon_AgentDefinition_Tracon_AgentDefinition_"></a> operator ==\(AgentDefinition?, AgentDefinition?\)

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

#### Parameters

`left` [AgentDefinition](/api/tracon.agentdefinition/)?

`right` [AgentDefinition](/api/tracon.agentdefinition/)?

#### Returns

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

### <a id="Tracon_AgentDefinition_op_Inequality_Tracon_AgentDefinition_Tracon_AgentDefinition_"></a> operator \!=\(AgentDefinition?, AgentDefinition?\)

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

#### Parameters

`left` [AgentDefinition](/api/tracon.agentdefinition/)?

`right` [AgentDefinition](/api/tracon.agentdefinition/)?

#### Returns

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