# IAgentExtension

> 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.iagentextension/
> Summary: IAgentExtension: A named piece of code that reaches the Microsoft Agent Framework options the compiler builds for an agent. A definition selects it by IAgentExtension.Name in.

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

A named piece of code that reaches the Microsoft Agent Framework options the
compiler builds for an agent. A definition selects it by
[IAgentExtension.Name](/api/tracon.iagentextension/#Tracon_IAgentExtension_Name) in [AgentDefinition.ExtensionNames](/api/tracon.agentdefinition/#Tracon_AgentDefinition_ExtensionNames).

```csharp
public interface IAgentExtension
```

## Remarks

This is the escape door for a Microsoft Agent Framework option Tracon does not
model, for an `AIContextProvider` of your own, or for a chat client that must
see every model call ([AgentExtensionContext.UseChatClient](/api/tracon.agentextensioncontext/#Tracon_AgentExtensionContext_UseChatClient_Tracon_ChatClientSlot_System_Func_Microsoft_Extensions_AI_IChatClient_Microsoft_Extensions_AI_IChatClient__)). The agent still goes
through the compiler, so it keeps the model ring, the tenant's provider
credential, egress and cost; a hand-built agent in
`AddAgent(name, factory)` loses them.

The same boundary as tools applies: code defines, data selects. The name is all
a stored definition carries; the user interface cannot write the code behind it.

[IAgentExtension.Configure](/api/tracon.iagentextension/#Tracon_IAgentExtension_Configure_Tracon_AgentExtensionContext_) runs when an agent is compiled, not on every run. The
compiled agent is cached per tenant, agent name and definition, so the result
serves the runs of that agent that follow. Two runs that start before the cache
holds the agent can each compile it. An agent compiled with parameter values, and
an agent of a tenant that holds its own provider key, is not cached and runs the
extension each time. Keep the call cheap, keep the extension free of state that
belongs to one run, and take services from
[AgentExtensionContext.Services](/api/tracon.agentextensioncontext/#Tracon_AgentExtensionContext_Services) (the root provider; a request-scoped
service is not available).

**Lifetime.** One `singleton` instance serves every agent and every
tenant. An implementation must be thread-safe: two tenants compile the same
extension at the same time. A registration by type resolves it from the container once.

**Tenant.** The mode is `expected tenant`: the tenant the agent is
compiled for arrives in [AgentExtensionContext.TenantId](/api/tracon.agentextensioncontext/#Tracon_AgentExtensionContext_TenantId), and the extension
does not read an ambient tenant. The compiled-agent cache key carries the tenant, so a
result built for one tenant never serves another.

**Delivery.** `No delivery guarantee applies`: [IAgentExtension.Configure](/api/tracon.iagentextension/#Tracon_IAgentExtension_Configure_Tracon_AgentExtensionContext_)
is a compile-time callback, not a message. It runs once per compilation of an agent
that names the extension, and a failure fails that compilation; nothing is retried or
queued. After a deployment that changes an extension, an agent already compiled keeps
the old result until its definition changes or the process restarts.

## Properties

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

Gets what the extension does, in one sentence, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null). The
console shows it next to the name and `GET /api/agent-extensions`
returns it to every reader, so it must not carry a secret.

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

#### Property Value

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

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

Gets the name a definition uses to select this extension. It is 1 to 128
characters of lowercase ASCII letters, digits, `.`, `_` or `-`,
and unique among the registered extensions.

```csharp
string Name { get; }
```

#### Property Value

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

## Methods

### <a id="Tracon_IAgentExtension_Configure_Tracon_AgentExtensionContext_"></a> Configure\(AgentExtensionContext\)

Changes the options of the agent that is being compiled, adds a wrapper
around it, or adds a chat client ring to its model pipeline.

```csharp
void Configure(AgentExtensionContext context)
```

#### Parameters

`context` [AgentExtensionContext](/api/tracon.agentextensioncontext/)

The agent being compiled.

#### Remarks

The compiler checks the options after the call. A member the definition or a
Tracon tenant and security decision owns must come back unchanged; if it does
not, the compilation fails with a [TraconCompilationException](/api/tracon.traconcompilationexception/) that
names this extension and the member. An exception thrown here fails the
compilation the same way.