.NET API
AgentDefinition
Tracon.Abstractions.dllThe 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.
public sealed record AgentDefinition : IEquatable<AgentDefinition>- Inheritance
- object ← AgentDefinition
- Implements
- IEquatable<AgentDefinition>
- Inherited Members
- object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Remarks
Section titled “Remarks”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. 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
Section titled “Constructors”AgentDefinition()
Section titled “ AgentDefinition()”public AgentDefinition()Properties
Section titled “Properties”CallableAgents
Section titled “ CallableAgents”Gets the other agents this agent may call, each with the version of it that runs.
public IReadOnlyList<CallableAgentReference> CallableAgents { get; init; }Property Value
Section titled “Property Value”IReadOnlyList<CallableAgentReference>
Remarks
Section titled “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 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).
A child agent runs in the same tenant and cannot change the tenant.
Compaction
Section titled “ Compaction”Gets the context compaction settings. When null no compaction is applied.
public CompactionSettings? Compaction { get; init; }Property Value
Section titled “Property Value”Description
Section titled “ Description”Gets a short description of what the agent does.
public string? Description { get; init; }Property Value
Section titled “Property Value”DisplayName
Section titled “ DisplayName”Gets the name shown in the user interface. Name is used when it is empty.
public string? DisplayName { get; init; }Property Value
Section titled “Property Value”ExtensionNames
Section titled “ 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.
public IReadOnlyList<string> ExtensionNames { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”A list of names only, never code - the same boundary as 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.
Harness
Section titled “ Harness”Gets the harness settings. When null a plain chat agent is produced; when populated, harness capabilities such as context compaction and todo tracking are enabled.
public HarnessSettings? Harness { get; init; }Property Value
Section titled “Property Value”Instructions
Section titled “ Instructions”Gets the system instructions passed to the model.
public string? Instructions { get; init; }Property Value
Section titled “Property Value”InstructionsByCulture
Section titled “ 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.
public IReadOnlyDictionary<string, string>? InstructionsByCulture { get; init; }Property Value
Section titled “Property Value”IReadOnlyDictionary<string, string>?
McpResourceUris
Section titled “ 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.
public IReadOnlyList<string> McpResourceUris { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “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.
Memory
Section titled “ Memory”Gets the memory provider settings. When null no memory provider is added.
public MemorySettings? Memory { get; init; }Property Value
Section titled “Property Value”Metadata
Section titled “ Metadata”Gets free-form, application-specific metadata.
public IReadOnlyDictionary<string, JsonElement> Metadata { get; init; }Property Value
Section titled “Property Value”IReadOnlyDictionary<string, JsonElement>
Gets the provider and model binding to use.
public required ModelBinding Model { get; init; }Property Value
Section titled “Property Value”Gets the unique name of the agent, used as the key in the catalog and in API routes.
public required string Name { get; init; }Property Value
Section titled “Property Value”Origin
Section titled “ Origin”Gets the origin of the definition: code or database.
public AgentDefinitionOrigin Origin { get; init; }Property Value
Section titled “Property Value”Parameters
Section titled “ Parameters”Gets the schema of named placeholders ({{name}}) this definition’s
instructions may reference.
public IReadOnlyList<AgentParameter> Parameters { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”Validated at compile time: see AgentParameter. A run
supplies concrete values through AgentRunRequest.Parameters; the
definition itself carries only the schema, never a value.
SharedInstructionsName
Section titled “ SharedInstructionsName”Gets the name of another definition whose Instructions text is
prepended to this definition’s own resolved instructions at compile time.
public string? SharedInstructionsName { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”A shared instructions block is an ordinary 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.
SkillNames
Section titled “ 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.
public IReadOnlyList<string> SkillNames { get; init; }Property Value
Section titled “Property Value”Skills
Section titled “ Skills”Gets how this agent uses its skills. When null, all three skill
tools ask for approval. Ignored when SkillNames is empty.
public SkillSettings? Skills { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”An agent exposed over A2A or MCP must turn the read approval off, or the host refuses to expose it. See SkillSettings.DisableReadApproval.
SubAgents
Section titled “ SubAgents”Gets how this agent calls the agents it may call
(SubAgentSettings.CallMode) and how long it waits for them. When
null, the agent uses background tasks and
TraconAgentGraphOptions.ChildDeadline and WaitTimeout apply.
Ignored when CallableAgents is empty.
public SubAgentSettings? SubAgents { get; init; }Property Value
Section titled “Property Value”TenantId
Section titled “ TenantId”Gets the tenant this definition belongs to. A single-tenant setup uses the default value.
public string? TenantId { get; init; }Property Value
Section titled “Property Value”ToolNames
Section titled “ 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.
public IReadOnlyList<string> ToolNames { get; init; }Property Value
Section titled “Property Value”UpdatedAt
Section titled “ UpdatedAt”Gets the time the definition last changed (UTC).
public DateTimeOffset? UpdatedAt { get; init; }Property Value
Section titled “Property Value”Version
Section titled “ Version”Gets the definition version. Every save increments it, and the store owns the number: the value on an incoming definition is ignored.
public int Version { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “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.
Workspace
Section titled “ Workspace”Gets the session workspace settings. When null the agent has no workspace.
public WorkspaceSettings? Workspace { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “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.
Methods
Section titled “Methods”Equals(object?)
Section titled “ Equals(object?)”public override bool Equals(object? obj)Parameters
Section titled “Parameters”obj object?
Returns
Section titled “Returns”Equals(AgentDefinition?)
Section titled “ Equals(AgentDefinition?)”public bool Equals(AgentDefinition? other)Parameters
Section titled “Parameters”other AgentDefinition?
Returns
Section titled “Returns”GetHashCode()
Section titled “ GetHashCode()”public override int GetHashCode()Returns
Section titled “Returns”ToString()
Section titled “ ToString()”public override string ToString()Returns
Section titled “Returns”Operators
Section titled “Operators”operator ==(AgentDefinition?, AgentDefinition?)
Section titled “ operator ==(AgentDefinition?, AgentDefinition?)”public static bool operator ==(AgentDefinition? left, AgentDefinition? right)Parameters
Section titled “Parameters”left AgentDefinition?
right AgentDefinition?
Returns
Section titled “Returns”operator !=(AgentDefinition?, AgentDefinition?)
Section titled “ operator !=(AgentDefinition?, AgentDefinition?)”public static bool operator !=(AgentDefinition? left, AgentDefinition? right)Parameters
Section titled “Parameters”left AgentDefinition?
right AgentDefinition?