Reference

Compatibility

Use this page before you choose a target framework, database, model provider, or deployment shape. A check means the package makes that promise. A dash means the capability does not apply; it does not mean “probably works.”

Target frameworks

Artifact	Target	Notes
Runtime packages	`net8.0`, `net9.0`, `net10.0`	This includes Core, all providers, all SQL packages, AspNetCore, MCP, Workflows, UI, and Voice
`Tracon.Testing`	`net8.0`, `net9.0`, `net10.0`	The test host resolves its ASP.NET Core hosting dependency per framework, so it matches the runtime matrix
`Tracon.Templates`	Generates `net10.0`	It is a content package, not a runtime assembly
Embedded source generator	`netstandard2.0`	It ships through `Tracon.Core`; `Tracon.Generators` is not a separate public NuGet package

The runtime packages and Tracon.Testing build for all three targets. Only part of that matrix is also run on each target. In Tracon’s own CI a representative set of test suites runs on net8.0, net9.0, and net10.0: Core, the four model providers, the shared SQL layer, SQLite storage, and the extension contract suite. The other suites (ASP.NET Core hosting, MCP, Workflows, Voice, the console, and the PostgreSQL and SQL Server stores) run on net10.0 only. Before a release, a net8.0 console application restores the packed Tracon.Core package and runs an agent on the .NET 8 runtime.

The packages are still pre-release. Install them with an explicit preview version or the CLI’s pre-release option. The template package also needs a preview version or pre-release selection.

How long each target framework stays

Tracon follows Microsoft’s own .NET support lifecycle and does not extend it. A target framework stays in the matrix while Microsoft still supports it; once that support ends, a later Tracon release may drop it.

Plan for this before it happens, because it changes what you can upgrade to:

Dropping an out-of-support target framework is not treated as a breaking change under the versioning policy. It can land in a minor release.
A release that drops one says so in its changelog entry, and the package’s own net8.0/net9.0/net10.0 assets simply stop appearing.
Your application keeps working on the release it already resolved; nothing is withdrawn from nuget.org. What ends is new Tracon releases for that framework.

Support dates come from Microsoft, not from Tracon, and they move: check the .NET support policy for the current end-of-support date of each version before you pin one. net10.0 is the longest-lived target in the matrix today, and a new application should start there.

Scheduled (announced 2026-09-23): net8.0 and net9.0 reach the end of Microsoft support on 2026-11-10. The first Tracon release after that date drops both targets. An urgent security release may still carry them. Move an application that targets net8.0 or net9.0 to net10.0 before you take that release.

The 21 packages

“Meta” shows whether dotnet add package Tracon brings the package into the dependency graph. AOT states the promise made by the package itself.

Package	Meta	Frameworks	Native AOT	Purpose or limit
`Tracon`	—	net8/9/10 dependency groups	No	Meta package; it carries no assembly and includes packages that do not promise AOT
`Tracon.Abstractions`	Yes	net8/9/10	Yes	Contracts and data types only
`Tracon.Core`	Yes	net8/9/10	Yes	Catalog, compiler, decorators, in-memory stores, jobs, evaluation, and governance services
`Tracon.PostgreSql`	Yes	net8/9/10	Yes	Durable stores and the only built-in vector-search store
`Tracon.OpenAI`	Yes	net8/9/10	Yes	OpenAI Chat Completions, Responses, and named compatible endpoints
`Tracon.AspNetCore`	Yes	net8/9/10	No	Minimal API delegate routing uses reflection
`Tracon.Workflows`	Yes	net8/9/10	No	The MAF workflow engine uses reflection
`Tracon.Mcp`	Yes	net8/9/10	No	Runtime MCP schemas and the MCP SDK use reflection for JSON handling
`Tracon.UI`	Yes	net8/9/10	No	Embedded asset discovery plus its ASP.NET Core dependency
`Tracon.SqlServer`	No	net8/9/10	No promise	Measured clean, but no live-query AOT guarantee is made
`Tracon.Sqlite`	No	net8/9/10	No	`SQLitePCLRaw` carries a native library
`Tracon.Anthropic`	No	net8/9/10	No	Claude provider; the Anthropic SDK’s `IChatClient` adapter uses reflection-based JSON, so a Native AOT app fails on the first request
`Tracon.Google`	No	net8/9/10	No	Gemini provider; its credential library (`Google.Apis.Auth`) uses reflection-based JSON and a Native AOT publish emits about 100 trim and AOT warnings
`Tracon.Azure`	No	net8/9/10	Yes	Azure OpenAI provider (v1 API); managed identity stays consumer-selected
`Tracon.Voice`	No	net8/9/10	Yes	ElevenLabs speech tools and reusable speech contracts
`Tracon.AGUI`	No	net8/9/10	No	The AG-UI endpoint; it sits on `Tracon.AspNetCore`, whose minimal API routing uses reflection
`Tracon.Testing`	No	net8/9/10	No promise	Assertions use reflection and the test host uses runtime JSON serialization
`Tracon.Testing.Contracts.Xunit`	No	net8/9/10	No promise	Behavior contract suite for seven extension families — storage (`IRunStore` and 30 other store interfaces), model providers, run judges, agent sources, job handlers, skill script executors, and custom tools — as xunit.v3 fixtures; uses reflection for a build-time coverage check
`Tracon.Templates`	No	net10 output	N/A	`dotnet new tracon-api` content package
`Tracon.Client`	No	net8/9/10	No	Typed management client generated from the OpenAPI document; every request/response call is hand-wired to a generic `JsonSerializer` overload the trim/AOT analyzer cannot prove type coverage for
`Tracon.Cli`	No	net10 (`DotnetTool`)	No	The `tracon` global tool; wraps `Tracon.Client` and ships as IL, not native code

Tracon.Core remains AOT-compatible because reflection-based convenience calls carry [RequiresUnreferencedCode] and [RequiresDynamicCode]. For AOT, prefer AddGeneratedTools() or register an already-built AIFunction.

Storage engines

All SQL providers implement the same store contracts and run the same shared contract tests. The registration and provider-specific configuration still change.

Capability	In memory	PostgreSQL	SQL Server	SQLite
Survives process restart	No	Yes	Yes	Yes
Intended for multiple application nodes	No	Yes	Yes	No; use it for one node or local work
Run, event, session, job, eval, workflow, audit, and governance stores	Process lifetime	Durable	Durable	Durable
Conversation branching	No	Yes	Yes	Yes
Vector knowledge search	No	Yes, with pgvector	No; knowledge answers `501`	No; knowledge answers `501`
Object isolation	Process	Schema, default `tracon`	Schema, default `tracon`	Table prefix, default `tracon_`
Migration lock	None	PostgreSQL advisory lock	`sp_getapplock`	Sidecar file lock scoped to the database file and table prefix
Auto-apply migrations	N/A	On by default	On by default	On by default
Read contract view (`runs_v1`)	No	Yes, opt-in (`EnableReadViews`)	Yes, opt-in (`EnableReadViews`)	Yes, opt-in (`EnableReadViews`)
ORM	None	None	None	None
AOT promise	Yes through Core	Yes	No promise	No

SQLite has no schema. Do not use bare Data Source=:memory: with Tracon. The library opens more than one connection, so each bare in-memory connection would see a different database. Use a shared URI such as Data Source=file:tracon?mode=memory&cache=shared when a SQLite in-memory test is required.

PostgreSQL knowledge search also needs an IEmbeddingGenerator<string, Embedding<float>>. The vector dimension becomes part of the PostgreSQL column type. Changing the embedding dimension is a schema migration, not a live configuration change.

Agent Framework dependency versions

Seven packages depend on Microsoft Agent Framework or Microsoft.Extensions.AI. These are the versions they declare.

Package	Declared dependencies
`Tracon.Abstractions`	`Microsoft.Agents.AI.Abstractions` 1.25.0 · `Microsoft.Extensions.AI.Abstractions` 10.11.0
`Tracon.Core`	`Microsoft.Agents.AI` 1.25.0 · `Microsoft.Agents.AI.Harness` 1.25.0 · `Microsoft.Extensions.AI` 10.11.0 · `Microsoft.Extensions.AI.Evaluation` 10.11.0
`Tracon.Workflows`	`Microsoft.Agents.AI.Workflows` 1.25.0
`Tracon.OpenAI`	`Microsoft.Agents.AI.OpenAI` 1.25.0 · `Microsoft.Extensions.AI.OpenAI` 10.11.0
`Tracon.Azure`	`Microsoft.Extensions.AI.OpenAI` 10.11.0
`Tracon.Testing.Contracts.Xunit`	`Microsoft.Agents.AI` 1.25.0 · `Microsoft.Extensions.AI` 10.11.0
`Tracon.AspNetCore`	`Microsoft.Agents.AI.Hosting`, `.Hosting.AspNetCore`, and `.Hosting.A2A` at exactly a 1.25.0 pre-release · `.Hosting.OpenAI` at exactly a 1.25.0 alpha · `A2A.AspNetCore` at exactly `1.0.0-preview3`

Tracon.AspNetCore is the only package that carries a pre-release Agent Framework dependency, and it is the only one permitted to.

A pre-release dependency is an exact pin

The five pre-release entries of Tracon.AspNetCore are exact ranges, such as [1.25.0-preview.261014.1]. A pre-release package makes no compatibility promise between its own previews, and this one broke: Microsoft.Agents.AI.Hosting.AgentSessionStore left the Hosting assembly in 1.22.0-preview, so a project that raised Hosting under 1.0.0-preview.2 restored without a warning and failed at run time with a TypeLoadException.

With an exact range NuGet reports the same situation at restore instead. A direct reference to another version gives NU1608, and a package that needs another version gives NU1107. To move to a newer Hosting preview, move to the Tracon release that is built against it.

A stable dependency is a floor, not a pin

Every other entry above is a minimum. NuGet reads 1.25.0 as [1.25.0, ) and then resolves the lowest version that satisfies every constraint in the graph, so a project that asks for nothing else restores exactly the version listed. You get a different version only when something asks for one: a direct PackageReference to a higher version, or another package whose own floor is higher.

For a stable dependency Tracon declares no upper bound. A newer Agent Framework is allowed to resolve, and Tracon will not stop it.

What is tested, and what is promised

Tracon is built and tested against exactly the versions in the table. That is the whole of the promise.

The promise is about behaviour, not about compiling. Agent Framework types appear in only a few places on Tracon’s own public surface — AIAgent, AIFunction, and ChatMessage are the ones you are most likely to meet — so a newer Agent Framework will often still compile. Underneath that surface Tracon calls into the framework throughout its runtime. Compiling against an untested version is not evidence that it behaves the same, and a resolution that silently moved is the case where you would find out last.

To decide the version yourself instead of leaving it to the graph, reference the Agent Framework packages explicitly at the version you intend, or commit a lock file.

When Tracon moves the floor

A raised floor ships in a Tracon minor version and is named in the changelog. It can oblige you to take a newer Agent Framework, so read it as you would any other dependency bump. Tracon does not ship an upper bound to prevent one.

A version bump also reaches data you have already stored. The next section states which stored payloads survive it.

Persisted payload compatibility

Payload	Owner	Compatible across a Microsoft Agent Framework version bump?
`SessionRecord` envelope (id, tenant, timestamps, `Version`, `StateSchemaVersion`, `StateMafVersion`)	Tracon	Yes — a minor Tracon version only adds envelope fields
`SessionRecord.State`	Microsoft Agent Framework	No promise
`WorkflowCheckpointRecord` envelope	Tracon	Yes
`WorkflowCheckpointRecord.State`	Microsoft Agent Framework	No promise

See Versions and upgrades for what happens when a body cannot be read after an upgrade.

Model providers

Built-in catalogs start empty. A catalog drives selection, health display, and cost calculation; it never rejects an unlisted model or deployment.

Provider package	Stable name	Default endpoint	Authentication	Compatibility notes
`Tracon.OpenAI`	`openai`	OpenAI	API key	Chat Completions surface; rejects every `ModelBinding.ProviderSettings` key
`Tracon.OpenAI`	`openai-responses`	OpenAI	API key	Responses surface; registered with the official provider; rejects every `ProviderSettings` key
`Tracon.OpenAI` compatible registration	Caller-chosen name	Required or explicitly set by the caller	Optional for a local server	A second `{name}-responses` surface is opt-in because many compatible servers do not implement Responses; rejects every `ProviderSettings` key
`Tracon.Anthropic`	`anthropic`	Anthropic	API key	`max_tokens` is mandatory upstream; Tracon defaults the output limit to 4,096
`Tracon.Google`	`google`	Gemini Developer API	API key	Supports Google-specific safety and thinking settings in `ModelBinding.ProviderSettings`
`Tracon.Azure`	`azure-openai`	No global default; resource endpoint is required	API key or consumer `TokenCredential` factory	`ModelBinding.Model` contains an Azure deployment name, not the underlying model name; rejects every `ProviderSettings` key

The OpenAI-compatible path covers services such as OpenRouter and Groq and local servers such as Ollama, LM Studio, and vLLM. Compatibility means the selected server implements the surface you enable. It does not mean every server supports every model feature.

A harness agent’s hosted web search (HarnessSettings.EnableWebSearch, off by default) is such a feature. The Chat Completions surface (openai, azure-openai, and a compatible registration) accepts it only for search models and answers 400 for the others; the Responses surface offers it to every model.

UI, API, configuration, and code ownership

The console is an operator surface. It does not turn deployment authority into a web form. This matrix shows where a change can originate.

Item	Console	Management API	Host code or configuration	Rule
Executable tool implementation	View only	View only	Create and register	Tool code is code-only
Tool assignment to a database agent	Edit	Edit	Define	The tool must already be registered
Code-defined agent	View and run	View and run	Create and change	Code definitions are never edited in the console
Database-defined agent	Create, edit, diff, roll back	Create, edit, diff, roll back	Optional	The compiler validates before storage
Model-provider registration and credentials	View catalog and health	View catalog and health	Register and configure	Credentials never enter the database or UI
Model catalog and prices	View	Read	Configure	The catalog is informative, not an allowlist
Skills and stored skill content	Create and edit	Create and edit	Define in code or discover from configured roots	Script execution has additional deployment and grant gates
Skill-script grant	Manage in Skills	Manage	Configure the execution boundary	A grant cannot bypass disabled scripts or a missing interpreter
Workflow definition	Create, edit, diff, roll back, inspect, run	Create, edit, diff, roll back, inspect, run	Define in code	Code workflows are read-only in the console and keep no version history
Job schedule	Create, edit, trigger, delete	Create, edit, trigger, delete	Configure worker behavior	The job handler itself is code
Eval suite and experiment	Create and operate	Create and operate	Add custom checks and judges	Custom executable evaluation logic is code-only
Remote MCP server record	Manage	Manage	May seed or configure	Stored records refer to secret configuration keys, never secret values
Agent exposure as MCP or A2A	No	No	Explicit allowlist in `UseMcpServer()` or `UseA2A()`	External exposure is a deployment decision
Quota, API key, webhook, and retention policy	Settings panels	Manage	Supply defaults and secrets	Stored secrets are always references to configuration keys
Tenant	Show current tenant	Register and manage	Select resolver with `UseTenancy()`	There is no tenant-management screen
Authorization policy and role binding	Reflect effective access	No	ASP.NET Core configuration	Tracon stores no users or role assignments
Diagnostics endpoint	Use when present	Read when present	Enable in `MapTracon()` options	Off by default
Theme and language	Change locally	N/A	N/A	Browser preference; server messages stay English

The production profile is a versioned contract

RequireProductionProfile() asks about a fixed set of production decisions. That set is part of the compatibility contract, and it is the one place where a minor release can deliberately stop a host that used to start.

Question	Answer
Can a release add a decision to the profile?	Yes. It is the only way a newly recognised risk reaches a deployment that asked to be told
What happens to a host that calls the method?	It does not start until the new decision is answered or the risk is accepted by name
How is that announced?	As a behavioural breaking change in `CHANGELOG.md`, naming the new risk and saying why it was added — “hardened” on its own is not enough
What happens to a host that does not call the method?	Nothing. Every default stays exactly where it was; the profile changes no setting
Does accepting a risk survive the upgrade?	Yes. An accept names one risk and keeps applying to that risk alone

Read that cost before adopting the method. A deployment that wants its production decisions pinned rather than re-asked should pin the package version, not avoid the gate: the alternative is a new decision arriving in silence, which is the thing the method exists to prevent.

HTTP surface compatibility

The generated HTTP reference contains 177 management and OpenAI-compatible operations grouped under 23 domain tags.

Being in the reference and being live in your process are different questions. The document is generated from one build profile; whether a route answers depends on how you called MapTracon():

Route	In the reference	Live in your process
`GET /api/diagnostics`	Yes	Only when `EnableDiagnosticsEndpoint` is true
Voice conversation	No — a WebSocket, not an operation	Only after `UseVoiceConversation()`
MCP server routes	No	Only after `MapTraconMcpServer()`
A2A routes	No	Only after `MapTraconA2A()`
Health checks	No — they join your own health-check system	Wherever you put `MapHealthChecks()`
UI assets and SPA fallback	No — not API operations	Only after `UseUI()`

So a route present in the reference is not automatically enabled for you, and a route absent from it is not automatically unavailable.

The documented paths are relative to the prefix passed to MapTracon(). With the usual prefix, GET /api/agents means GET /tracon/api/agents.

API-key scopes

The JSON names are the PascalCase enum names below. Free-text scopes and names such as runs:write are invalid. A scope narrows a role; it never widens one. Effective authority is role ∩ scopes.

Scope	Opens
`RunsRead`	Run summaries, event streams, statistics, traces, and other run reads
`RunsWrite`	Starting and cancelling runs and deciding approvals
`AgentsRead`	Agent, skill, tool, and model catalog reads
`AgentsAdmin`	Agent and skill definition writes and version rollback
`ExternalInvoke`	Explicitly exposed MCP-server and A2A invocation surfaces
`KnowledgeRead`	Knowledge collection listing and semantic search
`KnowledgeAdmin`	Knowledge document upload and deletion
`WorkflowsRead`	Workflow definitions, version history, graphs, checkpoints, and pending requests
`WorkflowsAdmin`	Workflow definition writes, version rollback and deletion; running still needs `RunsWrite`
`EvalsRead`	Eval suites, cases, runs, and online-evaluation summaries
`EvalsAdmin`	Eval suite and case writes; triggering a run still needs `RunsWrite`
`ExperimentsRead`	Experiments, results, and canary status
`ExperimentsAdmin`	Experiment writes, start and stop, and canary policy
`PlatformRead`	Tenant, quota, retention, scheduling, webhook, diagnostics, and provider-health reads
`PlatformAdmin`	Platform configuration writes and retention execution; with `SecurityAdmin`, granting a stored skill script in a multi-tenant host
`SecurityAdmin`	API keys, skill-script grants (reading the content hash to grant needs `AgentsRead` too), and MCP OAuth start
`AuditRead`	Audit-trail reads

SecurityAdmin can create or extend authority. Grant it rarely. API keys are stored hashed and the plaintext value is returned only at creation.