Capability map

Tracon is a .NET package family that adds a control plane on Microsoft Agent Framework. You choose the pieces, keep control of the dependency graph, and run the control plane inside your own .NET application. This page is the inventory: what exists, where it lives, and what turns it on.

The shortest complete picture

flowchart LR
    accTitle: Tracon capability flow
    accDescr: Agent definitions enter the catalog, run with tools and context, persist state and telemetry, then feed evaluation and governance.
    DEF["Agent definitions"] --> CAT["Catalog and compiler"]
    CAT --> RUN["Runs and sessions"]
    RUN --> REC["Recording and telemetry"]
    RUN --> ORCH["Workflows and jobs"]
    RUN --> EXT["HTTP · OpenAI · MCP · A2A"]
    DEF --> CTX["Tools · skills · memory"]
    STORE["Memory or SQL stores"] --> CAT
    STORE --> RUN
    GOV["Security and governance"] --> RUN
    GOV --> EXT

The default AddTracon() registration is useful on its own. It gives you the catalog, compiler, in-memory stores, run pipeline, sessions, jobs, evaluation contracts, quotas, audit services, and other core services. Provider, SQL, UI, workflow, MCP, voice, and external protocol packages add their own explicit calls.

Agent design and model control

Capability	What it gives you	Enable or define it	Boundary
Declarative agents	Instructions, model binding, tools, skills, callable agents, metadata, and runtime policy as data	ITraconBuilder.AddAgent(AgentDefinition)	A code definition wins a name collision with a database definition
Factory agents	A direct escape hatch that returns any MAF AIAgent	AddAgent(name, factory)	The catalog still applies Tracon decorators. The agent skips the compiler: model rings only through IModelProviderRegistry.CreateChatClient (one warning per agent name if the chat client skips it), and no tenant provider key, egress policy, or cost; a custom agent source can apply those three. See Use any Microsoft Agent Framework feature
Agent extensions	Code that sets a Microsoft Agent Framework option, adds an AIContextProvider or a chat client ring, or wraps the compiled agent, while the agent keeps the model rings, the tenant’s key, egress, and cost	AddAgentExtension(name, configure); a definition selects it in AgentDefinition.ExtensionNames	Code defines, data selects. The compiler refuses a change to what the definition or the tenant owns (tool chain, chat history, file access, model settings). A tool a provider adds skips the tool chain
Database definitions	Create, validate, version, diff, roll back, and delete definitions at run time	HTTP API or console after MapTracon()	Code-defined agents are visible but read-only
Custom agent source	Lists agents from a repository or external runtime	AddAgentSource<T>(), instance, or factory	Custom agents are visible but read-only in the management API
Definition validation	Checks providers, tools, skills, callable agents, cycles, and policy before save	Compiler and POST /api/agents/validate	Validation does not call a model
Model binding	Provider, model, temperature, output limit, top_p, reasoning effort, and provider-specific settings	AgentDefinition.Model	Credentials stay in provider configuration, never in the definition
Structured output	Explicit text, JSON, or JSON Schema responses	ModelBinding.ResponseFormat	Provider support is validated or translated by that provider; an opt-in, fail-closed IStructuredResponseValidator seam can check the response before the run closes; a rejected response can get a bounded number of model-driven repair turns (MaxRepairAttempts), non-streaming runs only; a response cut off at the output limit fails as OutputTruncated and is never repaired (plain text completes with a tracon.output.truncated event); OpenAI and Azure OpenAI take strictJsonSchema, and POST /api/agents/validate shows the schema each provider receives
Agent graph	An agent calls other agents as tasks or tools, at a pinned version if set	CallableAgents	SubAgents.CallMode picks background tasks or one tool each. Shared limits bound call depth, total child runs, total token/cost spend, and wall-clock time — the token, cost, and time limits cut a run off mid-run, between model turns. Each call also has a two-layer wait limit (SubAgentSettings, or the installation-wide default): a cooperative deadline, then a hard cutoff that abandons a child that ignores cancellation
Harness mode	Context and iteration limits plus todo, file-memory, web-search, skill, and mode providers	AgentDefinition.Harness	The harness extends the agent; it does not replace MAF types. Its providers are on by default — each has its own Disable... flag
Harness loop	The agent is re-invoked until a declared stop criterion says the work is finished	HarnessSettings.Loop, plus AddLoopEvaluator() for a criterion written in code	Off unless the definition sets it. Five built-in criterion kinds take data only (agentReview makes another agent of the catalog the reviewer, as a child run); an unknown kind is refused at compile time. A factory gets the root services on the first compilation that names its kind. GET /api/loop-criteria lists the kinds and the judge model; the console edits the loop, and validation reports each loop problem with a path. The iteration ceiling is never open — an unset MaxIterations takes Tracon’s own default — and every iteration writes a LoopIterationCompleted run event that lists each evaluated criterion and names the judge model or the reviewer. OnExhausted / OnCriterionError set to LoopOutcome.FailRun fail the run instead of returning the last response (LoopUnsatisfied)
Context compaction	Trigger-based truncation or summarization with preserved turns and an optional utility model	AgentDefinition.Compaction and Tracon:UtilityModel	Compaction is per definition and can be disabled by harness settings
Working memory	Todo state, file memory, text search, vector search tools, and conversation memory (what a user said in earlier sessions)	AgentDefinition.Memory	Vector search also needs PostgreSQL and an embedding generator. Conversation memory is off by default, needs UseConversationMemory() and a registered VectorStore, is scoped by tenant, agent, and user, and its records go with their session. See Context and memory
Workspace	A private file area for one session of one agent, with the eight file_access_* tools	AgentDefinition.Workspace	Off by default. The tools run through the Tracon tool chain; a tool that changes a file always asks for approval. Size limits per file, session and tenant. The files go with the session. An exposed A2A or MCP agent needs a read-only workspace with no read approval. See Context and memory
Response caching	A tenant-, provider-, and tool-set-aware cache; a hit spends no tokens and opens no new trace span	ModelBinding.ResponseCache	Needs a registered IDistributedCache, or the agent fails to compile
Request fields	Seed, top-k, stop sequences, penalties, tool mode, parallel tool calls, and reasoning output are part of the definition	ModelBinding	Unset sends nothing; a provider states what its API surface sends (ISamplingSupport), and a field it would drop, on the primary model or a fallback, fails to compile and validation
Tool-call loop	The loop that runs a turn’s tool calls: concurrency, tolerated failed turns, and what an unknown tool does	ModelBinding.ToolLoop	AllowConcurrentToolCalls is off by default; each call still gets its own authorization, result, and metric; a fallback link takes the whole object
Parameterized instructions	Named {{name}} placeholders bound to a run’s own values	AgentDefinition.Parameters	Value substitution only — no expression, condition, loop, or field access
Workflow and queued run parameters	A workflow declares a schema; each agent step binds the values its own schema names; queued runs, batch items, replay, continuation and approval resume carry or repeat values	WorkflowDefinition.Parameters, WorkflowRunRequest.Parameters, GetRunParameters(), RunReplayRequest.Parameters	A run that recorded no values is not repeated for an agent with parameters; a code-defined workflow declares its schema in WorkflowRegistrationOptions.Parameters; jobs.payload is not content-protected
Shared instructions blocks	One definition’s instructions prepended to another’s at compile time	AgentDefinition.SharedInstructionsName	A block cannot reference another block

Tracon uses AIAgent, AgentSession, ChatMessage, and AIFunction directly. It is a control plane around MAF, not a competing agent abstraction.

Model providers

Several providers can be active at the same time. Each agent selects one by its stable provider name.

Package	Registration	Provider names	Notable capability
Tracon.OpenAI	UseOpenAI()	openai, openai-responses	Chat Completions and Responses clients
Tracon.OpenAI	UseOpenAICompatible(name, ...)	name, and optionally name-responses	OpenRouter, Groq, Ollama, LM Studio, vLLM, and other compatible endpoints
Tracon.Anthropic	UseAnthropic()	anthropic	Claude, with effort, adaptive or budgeted thinking, and prompt caching (TTL, breakpoint placement) settings
Tracon.Google	UseGoogle()	google	Gemini safety thresholds and thinking settings
Tracon.Azure	UseAzureOpenAI()	azure-openai	Azure deployments with an API key or a consumer-supplied Entra credential
Any package	AddModelProvider()	Chosen by the implementation	A custom IModelProvider without a provider package

All built-in providers can publish a configured model catalog. The catalog feeds the console and pricing; it is not an allowlist. Health checks are cached. A shared circuit breaker protects provider calls. Tracon does not invent model names or prices.

ModelBinding.Fallbacks decides whether a failure moves to the next provider link, and runs.error_class decides how a failed run is classified afterward. Both decisions can be overridden or composed with your own rules — see Write your own error classifier.

Tools, skills, and context

Capability	Registration or source	What is enforced
Generated tools	[TraconTool] and AddGeneratedTools()	Compile-time discovery without reflection or dynamic code; minimum/maximum/length/pattern constraints from standard DataAnnotations attributes reach the schema; a parameter may be a supported object (a public record or class with a single public constructor), up to 3 nested levels deep, bound through the tool’s own JsonSerializerContext
Direct tools	AddTool(AIFunction, configure)	Exact tool instance and its approval, effect, permission, timeout, repeatability, and output policy
Delegate tools	AddTool(delegate)	Convenient reflection path; trimming and dynamic-code warnings reach the caller
Scanned tools	AddToolsFrom<T>(), or the overload that takes a type	Only attributed methods become tools; this path uses reflection
Scoped tools	AddScopedTool	Every call gets its own DI scope, closed when the call ends
Argument validation	IToolArgumentsValidator	Runs before every call, code-defined or MCP; a rejection skips the real body
Tool approval	RequiresApproval, the registration flag, or AddToolApprovalPolicy()	A sensitive call cannot execute until a person or standing rule decides it
Tool output size limit	MaxOutputBytes (per tool) or Tools.DefaultMaxOutputBytes (installation-wide)	A result over the byte limit is trimmed into a JSON envelope before the model sees it; unlimited by default
Hosted tools	AddHostedTool(...)	A web search, code interpreter, or file search the model provider runs inside the model call; a definition selects it by name in ToolNames, and no approval, permission, or timeout applies. A provider states what its API surface runs (IHostedToolSupport); a kind it would drop fails to compile and validation. One tool per kind. Each call is priced with Tracon:Pricing:HostedTools:{provider}:{kind}:PerCall and is a tool event. See Hosted tools
Client-side tools	AddClientTool(...)	The declaration lives in code like every other tool; the server never runs the body. The model’s call comes back to the caller, which answers it with AgentRunRequest.ToolResults. An agent carrying one cannot be replayed in any tool mode — its call was never recorded, so no mode can answer it
Custom content guards	AddContentGuard<TGuard>()	Multiple guards run; the strictest result wins
Pattern guard	AddPatternContentGuard()	Denied terms can block; selected PII patterns can mask input or output
Skills	AddSkill() or database/file skill sources	Markdown instructions and resources are bounded and validated
Skill scripts	UseSkillScripts()	Explicit enablement, platform-isolation acknowledgement, interpreter allowlist, a content-pinned tenant grant (platform authority for a stored script in a multi-tenant host), one content size limit for stored and file scripts, timeout, output limit, and concurrency limits
Script executor	ISkillScriptExecutor registration	Runs an approved script in a container or a remote runner instead of a local process; gates, audit, quota, wait limit, and output cap stay with Tracon. See Write your own script executor
Remote MCP tools	UseMcp()	Tool discovery, name normalization, resource limits, authentication (credential headers by configuration key name), refresh, prompts, OAuth coordination, and a server’s request for user input: the run stops as AwaitingInput, the answer in the next request runs the call again (management run endpoint and AG-UI endpoint; every other surface gets decline) (how)
MCP resources	AgentDefinition.McpResourceUris	A bounded snapshot of selected server resources enters agent context
Knowledge search	PostgreSQL, IEmbeddingGenerator, and memory settings	Chunking, embedding, HNSW cosine search, tenant isolation, and result limits

Only application code defines executable tool logic. The console can edit which registered tools an agent may use, but it cannot create a new executable function. Stored skill scripts are a separate, deliberately gated feature; Tracon does not claim to provide an operating-system sandbox.

Runs, sessions, and media

Capability	Surface	Important behavior
Streaming runs	.NET or POST /api/agents/{name}/run	Text and tool activity stream as SSE events; a plain-text answer cut off at the output limit or the context window ends with a custom frame (tracon.output.truncated) before done
Non-streaming runs	.NET or an idempotent HTTP request	A completed response can be stored and replayed safely
Run recording	Core decorator pipeline	Default-on summaries, events, tool calls, usage, cost, errors, and optional input; content and workflow events Tracon has no type for are recorded as tracon.content and tracon.workflow.event (metadata only); it can be disabled and store failure never breaks the run
Custom run events	RunEventType.Custom and AgentRunScope.Writer	A tool writes its own named event into the stream a consumer already carries; the console draws it with a generic card, no code change required
Custom agent decorator	AddAgentDecorator<T>(), instance, or factory	Joins the built-in decorators; Order decides where
Cancellation	Run API and cancellation registry	A caller can request cancellation by run id while preserving the final recorded state
Replay	Recorded run input and replay service	Re-run against the current or selected definition, with tool replay modes and mismatch protection
Compare and score	HTTP API, console, or a custom IRunJudge	Compare two runs, attach human scores, or score completed runs automatically; a score carries a name, so one reviewer can rate the same run on several criteria; an online judge uses its provider setup credential and still obeys tenant egress policy
Sessions	AgentSessionManager and session endpoints	Durable conversation identity and readable history when the store supports it
Session ownership	Tracon:SessionOwnership	Off by default (false); records which user opened a session, narrows the session list to that user before paging, and answers 404 for another user’s session — sessions written before it was turned on stay unowned and appear only in the management listing, and RefuseUnownedSessions refuses those too once they no longer matter
Branching	Session branch API	Fork a durable conversation from an addressable item; SQL storage is required
Attachments	Attachment API and message references	Image, audio, PDF, and text uploads use size limits and magic-byte validation
Document channel	A run’s documents field	Reference text kept apart from instructions in the message list and the run record; a convention and an audit trail, not a security guarantee
Multimodal messages	MAF content types plus stored attachments	Providers receive supported image, audio, document, and text content without a new Tracon message abstraction
Image generation	UseOpenAIImages(), UseAzureOpenAIImages(), or UseGoogleImages() plus Tracon:Images	Optional generate_image tool stores a verified attachment and records image or token usage
Speech tools	Tracon.Voice and UseVoice()	ElevenLabs synthesis and transcription, or consumer implementations of the speech contracts; every speech call obeys the tenant’s egress policy; per-request provider settings (elevenlabs.*) are refused, never ignored, when unknown
Named speech providers	AddSpeechSynthesizer(), AddSpeechTranscriber(), and ISpeechProviderResolver	Several text-to-speech and speech-to-text engines in one process, selected by name from a workflow function node, POST /api/voice/speak, or GET /api/voice/voices; a tenant’s own key reaches only an engine that supports it, otherwise the call is refused rather than billed to the host; a Microsoft.Extensions.AI speech client binds to a name with TextToSpeechClientBinding or SpeechToTextClientBinding, UseOpenAISpeech() registers OpenAI speech as the provider openai, UseGoogleSpeech() Gemini speech as gemini
Multi-speaker dialogue	ISpeechProviderResolver.GetDialogueSynthesizerAsync() and ISpeechDialogueSynthesizer	Several voices in one request and one audio result, with each turn’s time range where the provider reports it, from a workflow function node; the built-in ElevenLabs client and UseGoogleSpeech() (two voices) implement it, and a request over the provider’s voice or character limit is refused rather than split
Live voice conversation	UseVoiceConversation() plus MapTracon()	A long-lived WebSocket joins transcription, an agent session, and synthesis; it is absent until registered
Provider-hosted live voice	UseLiveVoice() plus a provider such as UseOpenAILive()	The provider hosts the conversation and carries the media directly to the browser; Tracon creates the session so the key never leaves the server, and turns the work the model delegates into ordinary runs

A run is the unit of evidence. What is recorded is recorded against a run id, and a store failure never gets permission to stop the run itself — which is also the limit of the guarantee: recording is best-effort, so a store failure costs the record, not the run. Seven operations invert that and refuse to proceed without their audit entry; What is guaranteed to be written is the list.

Workflows and background work

Capability	Enable it	Storage and execution model
Multi-agent workflows	Tracon.Workflows, UseWorkflows(), and AddWorkflow()	Compiled graphs execute MAF workflow nodes and record a root run; a stored workflow keeps a version history that can be compared and rolled back, and a step can pin a version of a stored agent
Tenant run cap	MaxConcurrentRunsPerTenant	One tenant cannot take every workflow slot of a process or the front of the job queue: its run over the limit waits Queued for a tenant slot and holds no shared one, and a worker leases queued workflow jobs of a tenant under the limit first; across processes the count is read, not locked
Durable checkpoints	Workflow options and a SQL store	A workflow can resume after a restart instead of starting again; the resume compiles the definition version the run recorded, so an edit made while it waits changes nothing for it
Human input	Workflow request and response endpoints, WorkflowResponseMode	A waiting workflow resumes from its checkpoint as a new execution step; an agent’s tool call that needs approval is a request of the form ToolApproval (approve or refuse it, give a reason, optionally save a rule), where a pattern hosts the agent; every answer that starts a run is audited first, and a SingleAnswer workflow takes one answer per request (a repeat follows the first run, a different answer gets 409); GET /api/workflows/requests lists the tenant’s waiting requests, and a RequestTimeout closes a run nobody answered (run.failed) so retention can release what it kept
Job queue	Registered by AddTracon()	Leases, retries, items, status, cancellation, and handler dispatch
Custom jobs	IServiceCollection.AddJobHandler<THandler>(handlerKey)	A string handler key adds a new job type without changing the core queue; dispatch is an exact key match, so registration order never decides the winner, and execution is at-least-once. See Write your own job handler
Queue work from code	IJobDispatcher.EnqueueAsync()	Queues a job for a registered handler key and refuses one nobody serves
Workflow functions	AddWorkflowFunction<TInput, TOutput[, TSettings]>(), GetWorkflowFunction	A typed function runs as a graph node without an agent of its own; with a settings type, each workflow’s node carries values for it, checked when the workflow is saved; MaxConcurrency limits parallel calls per process; GetWorkflowFunction() and GetWorkflowAgentStep() give a graph built in code the same time limit, retry, budget gate, cost line and version pin (fixed in the graph, or read from a run parameter), and WorkflowRegistrationOptions.RunTimeout/Parameters add a run limit and a schema
Non-token usage	context.ReportUsageAsync()	A function node reports what it spent that is not tokens (speech characters, render seconds) and a tool reports with TraconToolUsage.Report; amounts in Tracon:Pricing:Currency add into a total beside the token cost that the call-tree budget, the tenant’s cost quota and run.completed count; a spent cost or time ceiling stops the next function node from starting, and a spent cost quota of the tenant does too (tenant_quota_exceeded), and WorkflowFunctionOptions.StartsWhenBudgetIsSpent exempts one from both; the ceiling is the logical run’s, so a run that continues an earlier one (an answer, a resume, a recovery) starts from what the earlier runs spent; an amount a tool reports after its run closed reaches the quota counter only. A unit is never added to another unit, and an item with no amount is unpriced, not free; GET /api/runs/{runId}/usage lists the items
Schedules	Scheduling API, console, or store	One-time and cron schedules enqueue work; time zones are explicit
Worker control	IServiceCollection.UseScheduling()	A process can run workers or act only as an API node
Async HTTP runs	Prefer: respond-async	The API returns 202 and a location while a worker owns execution; an agent run and a workflow run, resume or respond queue the same way
Idempotency	Idempotency-Key	Same tenant, operation, and key return the stored response instead of running twice; on the workflow run endpoints only with Prefer: respond-async
Singleton execution	Tracon:SingletonExecution	A distributed lease selects one active executor for singleton services
Run reconciliation	Tracon:RunReconciliation	Heartbeats let a scanner fail orphaned runs after process loss
Run continuation	Tracon:RunContinuation	An orphaned, session-bound agent run at the root of its tree resumes as a new run; completed tool calls replay, a destructive or external one blocks continuation unless the tool declares SafeToRepeat; a workflow run is resumed from its checkpoints instead
Workflow recovery	UseWorkflows(o => o.ResumeInterruptedRuns = true)	A queued workflow run or batch item interrupted by a crash, a deploy or a graceful stop continues from its latest checkpoint when its job is leased again, as a new run linked by ContinuedFromRunId, up to MaxResumeAttempts; the step in progress runs again
Workflow node retry	AddWorkflowFunction(..., retryPolicy: ...) or options.RetryPolicy	A transient provider error retries a single node without failing the run or costing an extra super-step
Time limits	options.Timeout, JobRequest.MaxDuration, a node’s timeout, a definition’s runTimeout, Tracon:Scheduling:MaxDurationByHandlerKey	A workflow step past its timeout fails the run (workflow_function_timeout, child_run_timeout); a definition shortens its run timeout, or lengthens it up to Tracon:Workflows:MaxRunTimeout, and its requestTimeout closes a run nobody answered; a job past its limit has its handler’s token cancelled and fails with tracon.job.max-duration-exceeded. A job cancel reaches a running handler within one PollInterval
Graceful drain	Tracon:Drain	A stop signal waits for in-flight runs and refuses new ones instead of cutting execution off

In-memory stores make these contracts usable for local work. Durable queues, checkpoints, schedules, cross-process leases, and recovery need a SQL provider for production behavior.

Evaluation and controlled change

Capability	Definition	Result
Eval suites and cases	API, console, or stores	Repeatable inputs, expected properties, checks, and run history
Built-in checks	Eval case configuration	Deterministic checks run without a judge model
Custom checks	AddEvalCheck(kind, check)	Application code adds a named MAF EvalCheck
Run judges	IRunJudge via AddRunJudge<T>(), instance, or factory, or the built-in AddModelRunJudge()	Manual or automatic scores with named criteria
Calibrated evaluator catalog	AddEvaluatorJudge(name, evaluator) with a Microsoft.Extensions.AI.Evaluation IEvaluator	Each metric the evaluator reports becomes its own {judge}.{metric} score row
Score provenance	RunJudgment.EvaluatorVersion, set automatically when you register an evaluator judge	Every score row records the version of the component that produced it, so a package upgrade is not read as a regression
Suite grading seam	AddEvalEvaluatorFactory<T>() or an instance	Replaces the MAF LocalEvaluator an eval suite is graded with
Online evaluation	Judge registration plus enabled sampling	A bounded sample of live runs is scored in the background
Eval run comparison	GET /api/evals/runs/{id}/diff or IEvalStore.DiffRunsAsync	Two runs of a suite align case by case into six buckets; added and dropped cases are never counted as regressions
Relative CI gate	tracon eval --baseline <runId|previous> --max-regressions <n>	A build fails on the cases that broke against an earlier run, not only on an absolute pass rate
Experiments	Experiment API and console	Stable traffic assignment compares agent versions and reports each arm separately
Canary rollback	Explicit canary policy	A background scan can stop or roll back a canary when its configured rule fails

Tracon reports evidence. It does not declare a statistical winner for an experiment, and automatic rollback is off until you configure it.

Security and governance

Capability	Where it applies	Default or gate
Loopback restriction	All mapped management surfaces	Remote access is off by default
Static bearer token	MapTracon() options	Optional; compare uses constant time
ASP.NET Core policy	RequireAuthorization(policy)	Uses your authentication and identity pipeline
Reader, Operator, Admin roles	Endpoint groups	Optional policy names; production can require all three at startup
API keys	HTTP API and stores	Hashed, revocable, expiring, tenant-bound, and narrowed by a closed scope enum
Multi-tenancy	UseTenancy()	Single tenant by default; a verified key outranks a claim or header
Session ownership	Tracon:SessionOwnership	A second boundary drawn under the tenant; off by default (false), and while off nothing changes. The owner comes from IRunAttributionContext and is never read from a request body. RefuseUnownedSessions extends it to the rows that predate it, while a session that does not exist yet is still opened by its first turn
Quotas	Run admission	Enabled with an empty rule set, so no run is rejected until a rule exists; every run of a call tree adds its own tokens and cost when it ends, a background child after its root included; a crossed threshold can also be written into the triggering run’s own event stream, off by default
Rate limiting	HTTP requests	Off by default; partition by tenant, key, or remote address
Approvals	Tool execution and queued resume	Expiring requests, explicit decisions, and revocable standing rules
Audit trail	Administrative writes	Actor, action, entity, before/after data, secret masking, and a per-tenant hash chain; best-effort except for eight fail-closed operations
Webhooks	Signed outbound events	HTTPS, SSRF checks, response limits, reserved-header rejection, credential headers by configuration key name, retry jobs, and failure disablement
Outbound network guard	Tracon:Egress	One guard for webhook delivery, MCP connections, and provider endpoints; private network targets refused by default, checked inside the socket connect callback
Configuration key prefixes	Stored secret references	A record stores a key name, never a value, and each name must sit under an allowed prefix; a credential-looking plain header is refused
At-rest content protection	AddContentProtection(...)	Off by default; AES-256-GCM encrypts session state, chat history, run inputs and events, tool arguments/results, agent files, and attachments before they reach the database
Retention and archive	Stored operational data	Deletion defaults are off (false); preview and jobs make cleanup explicit
Content inspection	Model input and output	No guard cost until a guard is registered
External surface guard	MCP server and A2A	Requires the ExternalInvoke scope and refuses an unsafe remote-access combination
Cross-origin access	TraconEndpointOptions.AllowedOrigins	Empty by default; no Access-Control-Allow-Origin header is ever sent until an exact origin is added — there is no wildcard option
Production profile gate	RequireProductionProfile()	Off by default, and it changes no setting and secures nothing by itself. It refuses to start the host while tenant separation, session ownership, at-rest protection, content inspection, rate limiting, or retention is still on its permissive default and the risk has not been accepted by name

An API-key scope never grants a role. Effective authority is the intersection of the caller’s role and key scopes. See the complete scope table in Compatibility.

Observability and operations

Capability	Output	Control
Run event stream	Gapless, ordered domain events	Recording options choose deltas, tool payloads, input, and payload size
OpenTelemetry traces	ActivitySource spans	Your exporter remains in control; Tracon can also persist a sample
Metrics	Run counts, duration, tokens, cost, tools, errors, judges, background-job executions and attempt duration, plus optional quota and job-queue-depth gauges	Standard .NET metrics; high-cardinality tags are bounded and store-backed gauges are opt-in and cached
Cost attribution	Per model, agent, run, child run, voice, and image usage	Prices come from a model catalog or explicit configuration; image prices are never inferred. A model no price source covers is named at startup and in GET /api/diagnostics rather than recorded as free. cost is the token cost; what nodes and tools reported beyond tokens is nonTokenCost on the run
Provider health	Cached status and optional background polling	On-demand by default; a provider without a health check reports Unknown
Health checks	AddTraconHealthChecks()	Adds checks to the consumer’s health-check system; you choose the route with MapHealthChecks()
Diagnostics report	GET /api/diagnostics and console	Endpoint is off by default because it reveals deployment shape
Retention preview	HTTP API and console	Shows eligible rows before a cleanup job changes data
Package family alignment	Host start	Always on; a host whose Tracon package assemblies (all but Tracon.Client) come from more than one release stops before any hosted service runs, and the error names each assembly and version

Observability never changes behavior. Every signal here is a side effect of a run, and a failure to record one is logged and stepped over rather than raised to the caller. Package family alignment is the one start-up guard in this table: it refuses a mixed graph instead of reporting it.

Integration surfaces

Surface	Registration	Intended caller
.NET API	AddTracon() and IAgentCatalog, tuned with ITraconBuilder.Configure(...) and extended through ITraconBuilder.Services	Application code that wants direct MAF objects
Management HTTP API	MapTracon()	The embedded console, automation, or your own client
Typed management client	Tracon.Client’s AddTraconClient()	.NET code calling a running instance from outside the process that hosts it; every SSE endpoint also has a ...StreamAsync method yielding one raw frame at a time
Typed TypeScript client	@tracon/client’s createTraconClient()	Browser or Node.js code calling a running instance from outside the process that hosts it; parseAs: 'stream' plus the exported readSse decoder reads an SSE endpoint
CLI	tracon global tool (Tracon.Cli)	Deployment pipelines: migrate/migrate status apply schema without starting the application, state-check reports read-only whether this build can still read the stored session and checkpoint state before an upgrade, health checks model provider health, eval gates a build on agent quality, absolutely or against an earlier run
OpenAPI	Your application’s AddOpenApi() setup	Client generation and API exploration
OpenAI compatibility	Included in MapTracon()	Existing Chat Completions, Responses, and Conversations clients
Embedded console	Tracon.UI and UseUI()	Operators, developers, evaluators, and security administrators
Embeddable chat widget	Tracon.UI’s embed.js asset (served once UseUI() is registered)	A page you embed the widget in, running under its own origin
MCP client	Tracon.Mcp and UseMcp()	Agents that consume tools from remote MCP servers
MCP server	UseMcpServer() and MapTraconMcpServer()	External MCP clients that invoke explicitly exposed agents as tools
AG-UI endpoint	Tracon.AGUI and MapTraconAGUI()	A front end that speaks AG-UI (CopilotKit and others); tool approvals and requests for input are interrupts. See AG-UI front ends
A2A server	UseA2A() and MapTraconA2A()	External agents that invoke an explicit allowlist of Tracon agents; a contextId continues a conversation scoped to the caller
Voice WebSocket	UseVoiceConversation() and MapTracon()	Browser or native real-time audio clients
Live voice sessions	UseLiveVoice(), a live provider, and MapTracon()	Browsers that speak to a provider-hosted model over WebRTC while Tracon supervises the session

MapTracon() exposes the documented management and OpenAI operations. The diagnostics endpoint, voice WebSocket, health route, MCP server, and A2A routes are conditional or separately mapped, so they are not all represented by the generated 177-operation HTTP reference.

Embedding points

Capability	What it gives you	Enable or bind it	Boundary
Tenant resolution	Resolves the current tenant from your own identity layer	ITenantContext, ITenantStore	AmbientTenantScope carries the tenant into background work outside an HTTP request
Run attribution	Attributes a run to your own user and job labels	IRunAttributionContext	Unset by default; the columns stay NULL until you register one
Tool authorization	Decides whether a caller may invoke a specific tool	IToolAuthorizationHandler	Allows every call by default; a thrown exception denies the call
Run and session authorization	Decides whether a caller may start a run, reach an existing run’s resources, or read/list/delete/branch/speak into a session	IRunAuthorizationHandler	Allows every call by default; a thrown exception denies the call and is logged as an error. Called explicitly at all six run-starting endpoints and at every run-resource endpoint, not one shared filter
Run event bridge	Bridges run events to your own channel or message bus	IRunEventSink	Queue the event and return; a slow sink degrades on its own, never the model stream
Attachment storage	Stores attachment content in your own object store	IAttachmentStorage	Content stays in the database until you register one
Tool-approval presentation	Turns a pending approval’s raw arguments into a resolved entity name	IToolApprovalPresenter	Best-effort: not registered, throws, or times out all publish the approval request unchanged

A registration made before AddTracon() wins over the built-in default. Each contract is registered with TryAdd, and GET /api/diagnostics reports which of the seven are still built-in. RequireCustomBinding<T>() turns a missed binding into a failed startup. A tool body reads the same identity (including UserId) through TraconRunContext, since it cannot reach AgentSession directly.

Coding-agent support

A coding agent working in your repository cannot use a capability it does not know exists. Three channels tell it. The first two are generated from this page and wait to be read; the third is a procedure the agent’s harness loads before the agent writes code, which is the only one that speaks first.

Capability	Enable it	Boundary
Agent map file	TraconWriteAgentsFile	Writes AGENTS.md at the repository root during build; an existing file is never overwritten
Local reference file	TraconWriteLocalReference, on by default with the map	Writes Tracon.LocalReference.md beside each project, naming the API documentation and the HTTP API document of the exact version that project restored; regenerated every build, never committed
Map for web agents	llms.txt and llms-full.txt	Published with this site; nothing to register. llms.txt carries the map and one line per documentation page; llms-full.txt carries every page in full. Any page also serves its markdown source at <address>index.md
Gate skill	tracon agent-skill	Writes .claude/skills/tracon/SKILL.md once, so the agent’s harness loads the procedure before it writes Tracon code; an existing file is never overwritten without --force, and the build reports a stale stamp as TRC0403
Usage diagnostics	Automatic with Tracon.Core; TraconUsageDiagnostics turns the family off	The Tracon.Usage category reports absent wiring, a literal secret, hand-written substitutes for shipped behaviour, instructions or a gate skill that leave the map unreachable or out of date, an ambient write that does not survive a streaming loop, and a discarded ambient scope
Tool diagnostics	Automatic with Tracon.Core	The Tracon.Tools category reports a tool method the generator cannot use

The map is refreshed by deleting AGENTS.md and building again; the file is never rewritten in place because you may have added notes to it. The project template sets the property, so a project generated from it has the map from its first build. A repository that already keeps its own AGENTS.md never receives the map file at all, and copying the capability list into it would only create a second copy to maintain: add one line naming Tracon.LocalReference.md instead, which is what TRC0402 asks for and what the first section of that file answers.

The map names every entry point; it explains none of them. Tracon.LocalReference.md answers the next question by pointing at what is already on your disk: the XML documentation each package carries into the NuGet cache, where every entry point carries a worked example, and the OpenAPI document that Tracon.AspNetCore ships. One file is written beside each project, not one at the repository root: a solution that splits a web host from a worker gives each project a different set of packages, and one shared file could hold only one of those answers. The paths are specific to your machine and to the versions that project restored, so the file is regenerated on every build and belongs in .gitignore — the template’s .gitignore already covers it.

Storage and testability

Capability	Choice
Zero-infrastructure start	In-memory implementations for every required core store
PostgreSQL persistence	UsePostgreSql(); durable contracts plus pgvector knowledge search
SQL Server persistence	UseSqlServer(); durable contracts without vector knowledge search
SQLite persistence	UseSqlite(); durable single-node or local use with a native SQLite dependency
Store replacement	Register your implementation before Tracon; TryAdd* preserves the consumer registration
Provider-free tests	Tracon.Testing.FakeModelProvider scripts deterministic model turns
Integrated tests	TraconTestHost builds a real catalog and in-memory stores
Assertions	RunAssertions checks recorded runs without binding to a unit-test framework

In-memory stores make every contract usable before any database exists.

Use Compatibility before you choose packages for a target framework or native AOT application. Use Configuration for verified section names and defaults.

Read next

• Choosing packages — which of these capabilities each package carries
• Your first agent — the smallest application that uses any of them
• Configuration — the section names and defaults behind every row above