Tracon.Client 1.0.0-preview.10

Tracon.Client

A typed client for Tracon's management API, generated from its published OpenAPI document. Covers every /api/* operation: agents, runs, sessions, evals, workflows, tenants, and the rest of the control plane.

dotnet add package Tracon.Client --prerelease

Setup

services.AddTraconClient(options =>
{
    // The application root PLUS the MapTracon prefix. The default
    // prefix is "/tracon"; an app that called MapTracon("/control")
    // needs "https://example.com/control/" instead.
    options.BaseAddress = new Uri("https://example.com/tracon/");
    options.Token = configuration["Tracon:Token"]; // a secret - read it, don't hard-code it

    // Optional. HttpClient caps every request at 100 seconds by default, which
    // applies underneath any longer budget you set yourself. Timeout.InfiniteTimeSpan
    // leaves the budget entirely to the cancellation token you pass in.
    options.Timeout = TimeSpan.FromSeconds(30);
});

Resolve TraconApiClient from the container and call any of its generated methods — one per operation in the document:

var client = provider.GetRequiredService<TraconApiClient>();
var agents = await client.TraconListAgentsAsync(cancellationToken);

Streaming endpoints have a second method

Some endpoints answer with Server-Sent Events rather than JSON. Each of them has a ...StreamAsync sibling that hands you one raw SSE frame at a time, as the server flushes it:

await foreach (var frame in client.TraconRunAgentStreamAsync("support", request))
{
    Console.WriteLine(frame); // "id: 3\nevent: update\ndata: {...}"
}

Leaving the loop early, or cancelling the token, stops the read and releases the connection. Comment-only keep-alive frames are skipped.

The two OpenAI-compatible endpoints (/v1/responses, /v1/chat/completions) answer with either shape, chosen by the stream flag in the request body, so they have both methods and you pick one:

var body = JsonSerializer.SerializeToElement(
    new { model = "support", input = "Where is order 4182?", stream = true });

await foreach (var frame in client.TraconOpenAIResponsesStreamAsync(body))
{
    Console.WriteLine(frame);
}

The body is sent exactly as written — the client never rewrites stream to match the method. If the two disagree, the call throws TraconApiException with a message naming the fix, instead of failing obscurely later.

A request needs only what the document requires

Set the members the document marks required and nothing else; the call is valid.

await client.TraconCreateAgentAsync(new AgentDefinitionRequest
{
    Name = "support",
    Model = new ModelBinding { Provider = "openai", Model = "gpt-5.4-mini" },
});

await client.TraconSaveMcpServerAsync("docs", new McpServerRequest { Endpoint = "https://mcp.example.com/" });

A free-form member (ModelBinding.ProviderSettings, the Metadata of an agent or a skill, EvalSuiteSaveRequest.Checks, JobScheduleSaveRequest.Payload) is nullable and starts unset: the server reads an unset or null value as empty. A dictionary is an IDictionary<string, object>?, and Checks and Payload are JsonElement?. The client writes a dictionary value only if its type is one its JSON context knows: booleans, integers, double, string, JsonElement, nested dictionaries and string[]. A value of another type, such as decimal or a List<object>, throws NotSupportedException before the request is sent; pass it as a JsonElement.

A member the server fills in when it is left out starts with that value in the type, so the call means the same thing from every client. The MCP server above is registered enabled and with its approval gate on; a schedule runs in UTC and is enabled. The type shows the value (Enabled { get; set; } = true) and the document names it as default.

Why the base address needs the prefix

MapTracon's prefix is a runtime parameter, not a fixed value — the document every operation is generated from carries no prefix at all. If the client sent requests to the document's bare paths, a consumer that moved the mount point off the default /tracon would get a silent 404 on every call. TraconClientOptions.BaseAddress is where the prefix goes instead: it must be the address MapTracon is actually mounted at, with a trailing /.

The DTOs are not Tracon.Abstractions types

TraconApiClient's request and response types are generated straight from the OpenAPI document. They are not the same CLR types as Tracon.Abstractions's RunRecord, AgentDefinition, and so on — same shape, different type, because generating against the abstractions package would fight the code generator and would leak server-side interfaces (IRunStore and similar) into an HTTP consumer that never needs them.

Dependencies

No Tracon package. One NuGet package — Microsoft.Extensions.DependencyInjection.Abstractions, for AddTraconClient(this IServiceCollection ...) — which carries no transitive dependencies of its own. Serialization goes through a source-generated JsonSerializerContext, not runtime reflection; IHttpClientFactory is deliberately not used, for the same "no extra package" reason Tracon.Voice avoids it.

Links

• CLI (tracon global tool, uses this package for health): https://tracon.dev/guides/cli/
• Capability map: https://tracon.dev/capabilities/
• API reference: https://tracon.dev/api/

Licence: PolyForm Small Business 1.0.0 - free below 100 people and 1,000,000 USD (2019, inflation adjusted) revenue; a commercial licence applies above that. Terms ship in the package as LICENSE.md. Details: https://tracon.dev/reference/licensing/