# Tracon Tracon is a .NET package family that adds a control plane on Microsoft Agent Framework. Read this list before you write agent, run, tool, or evaluation code by hand: the capability is very likely already here. Tracon uses Microsoft Agent Framework types directly, so MAF documentation applies unchanged. ## Wiring ```csharp builder.Services.AddTracon(); // required: catalog, runs, in-memory stores app.MapTracon(); // optional: management HTTP API and console ``` Everything else is opt-in and named below. ## Packages - Tracon: meta package - Tracon.Abstractions: contracts and abstractions - Tracon.Anthropic: Anthropic (Claude) provider adapter - Tracon.AspNetCore: HTTP layer - Tracon.Azure: Azure OpenAI provider adapter - Tracon.Cli: The tracon global tool: applies pending… - Tracon.Client: Typed management client, generated from… - Tracon.Core: core runtime - Tracon.Google: Google Gemini provider adapter - Tracon.Mcp: Model Context Protocol client - Tracon.OpenAI: OpenAI provider adapter - Tracon.PostgreSql: PostgreSQL persistence layer - Tracon.Sqlite: SQLite persistence layer - Tracon.SqlServer: SQL Server persistence layer - Tracon.Templates: The dotnet new tracon-api template - Tracon.Testing: Test helpers: a non-networked model… - Tracon.Testing.Contracts.Xunit: Behavior contract suites extension points… - Tracon.UI: embedded management UI - Tracon.Voice: Voice tools - Tracon.Workflows: Workflow execution engine ## Capabilities ### Agent design and model control - Declarative agents: ITraconBuilder.AddAgent(AgentDefinition) - Factory agents: AddAgent(name, factory) - Database definitions: MapTracon() - Custom agent source: AddAgentSource() - Definition validation: POST /api/agents/validate - Model binding: AgentDefinition.Model - Structured output: ModelBinding.ResponseFormat - Agent graph: CallableAgentNames - Harness mode: AgentDefinition.Harness - Harness loop: HarnessSettings.Loop, AddLoopEvaluator(kind, evaluator) - Context compaction: AgentDefinition.Compaction, Tracon:UtilityModel - Working memory: AgentDefinition.Memory - Response caching: ModelBinding.ResponseCache - Concurrent tool calls: ModelBinding.AllowConcurrentToolCalls - Parameterized instructions: AgentDefinition.Parameters, parameters - Shared instructions blocks: AgentDefinition.SharedInstructionsName - Rule: Tracon uses AIAgent, AgentSession, ChatMessage, and AIFunction directly. ### Model providers - UseOpenAI(): Tracon.OpenAI, binds openai, openai-responses - UseOpenAICompatible(name, ...): Tracon.OpenAI, binds name, name-responses - UseAnthropic(): Tracon.Anthropic, binds anthropic - UseGoogle(): Tracon.Google, binds google - UseAzureOpenAI(): Tracon.Azure, binds azure-openai - AddModelProvider(): Any package - Rule: Several providers can be active at the same time. ### Tools, skills, and context - Generated tools: [TraconTool], AddGeneratedTools() - Direct tools: AddTool(AIFunction, configure) - Delegate tools: AddTool(delegate) - Scanned tools: AddToolsFrom(), AddToolsFrom(Type) - Scoped tools: AddScopedTool - Argument validation: IToolArgumentsValidator - Tool approval: RequiresApproval, AddToolApprovalPolicy() - Tool output size limit: MaxOutputBytes, Tools.DefaultMaxOutputBytes - Client-side tools: AddClientTool(...) - Custom content guards: AddContentGuard() - Pattern guard: AddPatternContentGuard() - Skills: AddSkill() - Skill scripts: UseSkillScripts() - Remote MCP tools: UseMcp() - MCP resources: AgentDefinition.McpResourceUris - Knowledge search: IEmbeddingGenerator - Rule: Only application code defines executable tool logic. ### Runs, sessions, and media - Streaming runs: POST /api/agents/{name}/run - Non-streaming runs: .NET or an idempotent HTTP request - Run recording: Core decorator pipeline - Custom run events: RunEventType.Custom, AgentRunScope.Writer - Custom agent decorator: AddAgentDecorator() - Cancellation: Run API and cancellation registry - Replay: Recorded run input and replay service - Compare and score: IRunJudge - Sessions: AgentSessionManager - Session ownership: Tracon:SessionOwnership - Branching: Session branch API - Attachments: Attachment API and message references - Document channel: documents - Multimodal messages: MAF content types plus stored attachments - Image generation: UseOpenAIImages(), UseAzureOpenAIImages() - Speech tools: Tracon.Voice, UseVoice() - Live voice conversation: UseVoiceConversation(), MapTracon() - Provider-hosted live voice: UseLiveVoice(), UseOpenAILive() - Rule: A run is the unit of evidence. ### Workflows and background work - Multi-agent workflows: Tracon.Workflows, UseWorkflows() - Durable checkpoints: Workflow options and a SQL store - Human input: Workflow request and response endpoints - Job queue: AddTracon() - Custom jobs: IServiceCollection.AddJobHandler(handlerKey) - Queue work from code: IJobDispatcher.EnqueueAsync() - Workflow functions: AddWorkflowFunction() - Schedules: Scheduling API, console, or store - Worker control: IServiceCollection.UseScheduling() - Async HTTP runs: Prefer: respond-async - Idempotency: Idempotency-Key - Singleton execution: Tracon:SingletonExecution - Run reconciliation: Tracon:RunReconciliation - Run continuation: Tracon:RunContinuation - Workflow node retry: AddWorkflowFunction(..., retryPolicy: ...) - Graceful drain: Tracon:Drain - Rule: In-memory stores make these contracts usable for local work. ### Evaluation and controlled change - Eval suites and cases: API, console, or stores - Built-in checks: Eval case configuration - Custom checks: AddEvalCheck(kind, check) - Run judges: IRunJudge, AddRunJudge() - Calibrated evaluator catalog: AddEvaluatorJudge(name, evaluator), Microsoft.Extensions.AI.Evaluation - Suite grading seam: AddEvalEvaluatorFactory() - Online evaluation: Judge registration plus enabled sampling - Eval run comparison: GET /api/evals/runs/{id}/diff, IEvalStore.DiffRunsAsync - Relative CI gate: tracon eval --baseline --max-regressions - Experiments: Experiment API and console - Canary rollback: Explicit canary policy - Rule: Tracon reports evidence. ### Security and governance - Loopback restriction: All mapped management surfaces - Static bearer token: MapTracon() - ASP.NET Core policy: RequireAuthorization(policy) - Reader, Operator, Admin roles: Endpoint groups - API keys: HTTP API and stores - Multi-tenancy: UseTenancy() - Session ownership: Tracon:SessionOwnership - Quotas: Run admission - Rate limiting: HTTP requests - Approvals: Tool execution and queued resume - Audit trail: Administrative writes - Webhooks: Signed outbound events - Outbound network guard: Tracon:Egress - Configuration key prefixes: Stored secret references - At-rest content protection: AddContentProtection(...) - Retention and archive: Stored operational data - Content inspection: Model input and output - External surface guard: MCP server and A2A - Cross-origin access: TraconEndpointOptions.AllowedOrigins - Rule: An API-key scope never grants a role. ### Observability and operations - Run event stream: Gapless, ordered domain events - OpenTelemetry traces: ActivitySource - Metrics: Run counts, duration, tokens, cost, tools, errors… - Cost attribution: Per model, agent, run, child run, voice, and image… - Provider health: Cached status and optional background polling - Health checks: AddTraconHealthChecks() - Diagnostics report: GET /api/diagnostics - Retention preview: HTTP API and console - Rule: Observability never changes behavior. ### Integration surfaces - .NET API: AddTracon(), IAgentCatalog - Management HTTP API: MapTracon() - Typed management client: Tracon.Client, AddTraconClient() - Typed TypeScript client: @tracon/client, createTraconClient() - CLI: tracon, Tracon.Cli - OpenAPI: AddOpenApi() - OpenAI compatibility: MapTracon() - Embedded console: Tracon.UI, UseUI() - Embeddable chat widget: Tracon.UI, embed.js - MCP client: Tracon.Mcp, UseMcp() - MCP server: UseMcpServer(), MapTraconMcpServer() - A2A server: UseA2A(), MapTraconA2A() - Voice WebSocket: UseVoiceConversation(), MapTracon() - Live voice sessions: UseLiveVoice(), MapTracon() - Rule: MapTracon() exposes the documented management and OpenAI operations. ### Embedding points - Tenant resolution: ITenantContext, ITenantStore - Run attribution: IRunAttributionContext - Tool authorization: IToolAuthorizationHandler - Run and session authorization: IRunAuthorizationHandler - Run event bridge: IRunEventSink - Attachment storage: IAttachmentStorage - Tool-approval presentation: IToolApprovalPresenter - Rule: Each contract is registered with TryAdd, so a registration made before AddTracon() wins over Tracon's built-in default, and GET /api/diagnostics reports which of the seven are still built-in. ### Coding-agent support - Agent map file: TraconWriteAgentsFile - Local reference file: TraconWriteLocalReference - Map for web agents: llms.txt, llms-full.txt - Usage diagnostics: Tracon.Core, TraconUsageDiagnostics - Tool diagnostics: Tracon.Core - Rule: A coding agent working in your repository cannot use a capability it does not know exists. ### Storage and testability - Zero-infrastructure start: In-memory implementations for every required core… - PostgreSQL persistence: UsePostgreSql() - SQL Server persistence: UseSqlServer() - SQLite persistence: UseSqlite() - Store replacement: TryAdd* - Provider-free tests: Tracon.Testing.FakeModelProvider - Integrated tests: TraconTestHost - Assertions: RunAssertions - Rule: In-memory stores make every contract usable before any database exists. ## Where to look - Exact local paths for the version you have: Tracon.LocalReference.md, beside each project that references Tracon - Capability map, with the boundary of each capability: https://tracon.dev/capabilities/ - Guides, concepts, and configuration reference: https://tracon.dev/ - Which page answers what, one line per page: https://tracon.dev/llms.txt - Full text of every hand-written page (about 700 KB - prefer one page above): https://tracon.dev/llms-full.txt - HTTP API reference: https://tracon.dev/http-api/ - .NET API reference: https://tracon.dev/api/ ## Which page answers what One line per hand-written page. Read the page that matches your question rather than the concatenated full text, which is far larger and answers the same question with everything else attached. - [Capability map](https://tracon.dev/capabilities/) — A complete map of Tracon capabilities, with the package, registration point, storage needs, and operational boundary of each feature. - [Agents and definitions](https://tracon.dev/concepts/agents/) — An agent as data, where definitions come from, how they are compiled, and what versioning gives you. - [Evaluation and experiments](https://tracon.dev/concepts/evaluation/) — Improve agents with regression suites, production-run promotion, online judges, human feedback, and controlled experiments. - [Governance](https://tracon.dev/concepts/governance/) — Govern agents with tenant isolation, audit, approvals, quotas, retention, content guards, API keys, and webhooks. - [Architecture](https://tracon.dev/concepts/) — The layers, the dependency direction, and the four conventions behind the default setup and the extension model. - [Runs and recording](https://tracon.dev/concepts/runs/) — Understand default-on run recording, ordered events, streaming, queues, errors, replay, comparison, and traces. - [Sessions and conversations](https://tracon.dev/concepts/sessions/) — Learn how sessions carry conversation state, how branching copies history, and how attachments are owned and removed. - [Tools, skills, and MCP](https://tracon.dev/concepts/tools/) — The ways an agent gains a capability, and the guards on the ones that cross the code-only boundary. - [Workflows](https://tracon.dev/concepts/workflows/) — Five multi-agent patterns, checkpoints, and asking a human mid-execution. - [Your first agent](https://tracon.dev/getting-started/first-agent/) — Build a Tracon host from an authorized source checkout, configure a model, and inspect your first recorded agent run. - [What Tracon is](https://tracon.dev/getting-started/) — What the packages give you, what they deliberately do not, and how to decide whether it fits. - [Persistence](https://tracon.dev/getting-started/persistence/) — Choose PostgreSQL, SQL Server, or SQLite and operate Tracon migrations safely from development to production. - [Securing the endpoints](https://tracon.dev/getting-started/security/) — Protect Tracon with network boundaries, bearer tokens, scoped API keys, roles, tenancy, and outbound guards. - [Adding a tool](https://tracon.dev/getting-started/tools/) — Register a tool so an agent can do something, and understand the one rule that trips people up. - [Background work](https://tracon.dev/guides/background-work/) — Queue agent runs, schedule recurring work, operate workers, and understand leasing, retries, cancellation, and multi-instance behavior. - [Typed client and CLI](https://tracon.dev/guides/cli/) — Call the management API from a typed client, and apply migrations or check health without starting the application, using the tracon CLI. - [Client-side tools and the embeddable widget](https://tracon.dev/guides/client-side-tools/) — Register a tool whose body runs in the browser, answer its call over HTTP, and drop the pre-built chat widget into your own page. - [Coding agents](https://tracon.dev/guides/coding-agents/) — Teach a coding agent what Tracon already does, via the capability map, a local reference file, and build-time diagnostics. - [Context and memory](https://tracon.dev/guides/context-and-memory/) — Control conversation history, compaction, working memory, MCP resources, and persistent knowledge without mixing their responsibilities. - [Two connection planes — EF Core and Tracon](https://tracon.dev/guides/ef-core/) — Share a PostgreSQL connection pool with your own EF Core DbContext without giving Tracon a dependency on Entity Framework. - [Embedding into a host application](https://tracon.dev/guides/embedding/) — Bind Tracon's seven embedding points to your own identity, authorization, eventing, storage, and approval presentation, and read the identity a tool body sees. - [Connect and expose agents](https://tracon.dev/guides/external-agents/) — Consume MCP tools and context, or publish selected Tracon agents through MCP and A2A with explicit security boundaries. - [Inbound triggers](https://tracon.dev/guides/inbound-triggers/) — Let an external system such as Slack start a queued agent or workflow run over a signed HTTP request, with no bearer token. - [Knowledge and RAG](https://tracon.dev/guides/knowledge/) — Ingest, chunk, embed, search, and bind tenant-scoped knowledge so agents can retrieve evidence through a controlled tool. - [Model providers](https://tracon.dev/guides/model-providers/) — Register OpenAI, Anthropic, Google, Azure OpenAI, or a compatible endpoint, then bind each agent without storing credentials. - [Multimodal input and generated images](https://tracon.dev/guides/multimodal/) — Upload images, documents, text, and audio safely, attach them to a run, or generate a durable image attachment with an agent tool. - [Observability](https://tracon.dev/guides/observability/) — Record and inspect runs, export OpenTelemetry signals, configure health checks, and diagnose storage, provider, and pricing failures. - [OpenAI-compatible API](https://tracon.dev/guides/openai-api/) — Point OpenAI clients at Tracon, choose an agent with model, stream responses, and understand the exact compatibility boundary. - [Production deployment](https://tracon.dev/guides/production/) — Deploy Tracon with durable storage, explicit access control, health checks, worker topology, retention, and safe secret handling. - [Reliable runs](https://tracon.dev/guides/reliability/) — Configure circuit breaking, idempotency, singleton execution, cancellation, and orphan reconciliation without hiding failure. - [Structured output](https://tracon.dev/guides/structured-output/) — Ask models for plain text, JSON, or JSON Schema output, validate definitions early, and treat every response as untrusted input. - [Test agents without model calls](https://tracon.dev/guides/testing/) — Test agents without network model calls by using the in-memory host, scripted fake provider, recorded requests, and run assertions. - [TypeScript client](https://tracon.dev/guides/typescript-client/) — Call the Tracon management API from TypeScript or JavaScript with a client generated from the OpenAPI document, typed end to end. - [Voice and live conversation](https://tracon.dev/guides/voice/) — Add speech tools and an opt-in realtime WebSocket conversation with explicit formats, limits, cost, privacy, and deployment rules. - [Write your own agent decorator](https://tracon.dev/guides/write-your-own-agent-decorator/) — Wrap every resolved agent with custom cross-cutting behavior via IAgentDecorator. - [Write your own agent source](https://tracon.dev/guides/write-your-own-agent-source/) — Add agents from Git, another database, or an external runtime through IAgentSource without bypassing Tracon's catalog and run pipeline. - [Write your own error classifier](https://tracon.dev/guides/write-your-own-error-classifier/) — Override which provider failures retry, and how a failed run is classified, without losing Tracon's built-in rules. - [Write your own job handler](https://tracon.dev/guides/write-your-own-job-handler/) — Implement a safe IJobHandler for the durable job queue and verify it with Tracon's executable contract suite. - [Write your own judge](https://tracon.dev/guides/write-your-own-judge/) — Implement a safe deterministic or model-backed IRunJudge and verify it with Tracon's executable contract suite. - [Write your own store](https://tracon.dev/guides/write-your-own-store/) — Implement IRunStore against your own persistence engine and prove it correct with the same contract suite the four shipped providers run. - [Write your own tool](https://tracon.dev/guides/write-your-own-tool/) — Build a safe custom tool without bypassing Tracon's authorization, approval, timeout, and output boundaries. - [HTTP API](https://tracon.dev/http-api/) — Use the Tracon management and OpenAI-compatible APIs with clear rules for auth, streaming, paging, errors, and schemas. - [Choosing packages](https://tracon.dev/packages/) — What each of the 20 packages does, which come with the meta package, and what enters your dependency graph. - [Release notes](https://tracon.dev/reference/changelog/) — Tracon has not been released yet; this page will carry the entry for each published version. - [Compatibility](https://tracon.dev/reference/compatibility/) — A verified compatibility matrix for target frameworks, packages, AOT, storage engines, model providers, UI ownership, and API-key scopes. - [Configuration](https://tracon.dev/reference/configuration/) — Verified configuration sections and defaults for Tracon core services, providers, persistence, operations, security, and optional surfaces. - [Glossary](https://tracon.dev/reference/glossary/) — Precise definitions for the Tracon terms used across agent design, execution, storage, security, evaluation, and operations. - [Licensing](https://tracon.dev/reference/licensing/) — Free for individuals, open source projects and small companies; larger companies buy a commercial licence. Which package carries which terms, and why. - [Read contract views](https://tracon.dev/reference/read-views/) — Query Tracon's run data directly with your own SQL or an EF Core keyless entity, through a versioned, read-only view instead of the internal tables. - [Versions and upgrades](https://tracon.dev/reference/versioning/) — Understand which Tracon release these docs describe, pin preview packages safely, and upgrade the full package family without drift. - [Troubleshooting](https://tracon.dev/troubleshooting/) — Symptom-first fixes for installation, providers, tools, storage, security, streaming, background work, MCP, voice, and the console. - [The console](https://tracon.dev/ui/) — Tour the embedded Tracon console by task, understand its security model, and know which features remain code or HTTP only.