CasCap.AgentRuntime.Client 1.7.0

CasCap.AgentRuntime.Client

Typed HTTP execution and definition-administration clients for .NET 10 and .NET 11 applications using the CasCap multi-tenant Agent Runtime. The application owns authentication, resilience and presentation; the runtime owns agent execution and session state.

Installation

dotnet package add CasCap.AgentRuntime.Client

The source targets net10.0 and net11.0 and depends on CasCap.AgentRuntime.Contracts. Use a stable .NET 11 SDK for source development; installed packages use their selected target's runtime.

Usage

In an existing Generic Host application (with Microsoft.Extensions.Hosting referenced), use the connection options below in the application's configuration:

using CasCap.AgentRuntime.Client.Abstractions;
using CasCap.AgentRuntime.Contracts.V1;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddAgentRuntimeClient();
using var host = builder.Build();

var client = host.Services.GetRequiredService<IAgentRuntimeClient>();
var response = await client.RunAgentAsync(
    "assistant",
    new RunAgentRequest
    {
        SessionId = "conversation-example",
        Input = "Summarize the available capabilities.",
    },
    CancellationToken.None);
Console.WriteLine(response?.OutputText);

Add a caller-owned authentication handler to the returned IHttpClientBuilder for authenticated deployments. The token needs agent.execute and its application identity must map to a runtime tenant. The snippet does not acquire a token.

Configuration Examples

Minimal connection settings:

{
  "CasCap": {
    "AgentRuntimeClientOptions": {
      "BaseAddress": "https://runtime.example.com/"
    }
  }
}

With an explicit timeout:

{
  "CasCap": {
    "AgentRuntimeClientOptions": {
      "BaseAddress": "https://runtime.example.com/",
      "TimeoutMinutes": 15
    }
  }
}

BaseAddress is required. TimeoutMinutes defaults to 10 and accepts 1–60. Both client registrations bind and validate these same options at startup.

Execution and Sessions

Register IAgentRuntimeClient with AddAgentRuntimeClient() and configure CasCap:AgentRuntimeClientOptions:BaseAddress and optional TimeoutMinutes. The registration returns an IHttpClientBuilder; authentication and resilience belong to the consuming application and are attached through that pipeline.

RunAgentAsync returns null when the named agent is unavailable to the authenticated tenant and throws for other non-success responses. Session methods inspect/reset/compact active state, manage named snapshots, and get or replace complete per-session runtime overrides without exposing raw session JSON. GetInstructionsAsync returns the effective instructions, or null when the agent is unavailable or its tenant has not enabled instructions disclosure.

StreamAgentAsync incrementally yields live delegation/compaction events and then the final response using a streamed JSON response. Callers opt into tool arguments and property bags through RunAgentRequest.IncludeDiagnosticDetails only when their diagnostic destination is operator-controlled. Unlike RunAgentAsync, streaming throws on any non-success response, including 404. The stream is a JSON array consumed incrementally, not Server-Sent Events.

Overlapping turns or mutations of the same session return HTTP 409, surfaced as HttpRequestException with StatusCode=Conflict. Reads remain available during a turn. Do not automatically retry interrupted runs or streams: a provider or tool may already have performed work. A stream that fails after its HTTP headers are sent terminates without a final response rather than changing its status code.

Document Knowledge

The current source adds SearchKnowledgeAsync and GetKnowledgePassageAsync to IAgentRuntimeClient. These require a caller-owned token with agent.knowledge.search, not merely agent.execute or agent.realtime. They return null on 404 and throw for other non-success responses.

Search sends one short query to the server's existing Azure embedding deployment only when an eligible corpus exists; it is not automatically invoked by RunAgentAsync or every prompt. Source previews do not invoke a model. Do not configure automatic retries for search: an uncertain embedding call may already have incurred usage. Tenant, collection and profile are server-owned. Responses contain bounded untrusted passages with protected generation/chunk references. The retrieval contract describes limits and pending rollout/consumer gates. These additions are not yet a published package.

Definition Administration

Register IAgentDefinitionAdminClient separately with AddAgentDefinitionAdminClient(). It publishes inactive immutable snapshots, reads active/version/history state, activates or rolls back versions, evaluates fixture scenarios, deactivates active definitions, and reads activation audit history. Attach control-plane credentials carrying definition scopes to that client; execution workloads need not receive those permissions.

The server can require a passing evaluation before activation. Deactivation requires a reason and is refused while another active agent delegates to the target.

Realtime Voice Calls

CreateRealtimeCallAsync sends a WebRTC SDP offer and returns the SDP answer and a runtime call id; EndRealtimeCallAsync ends the call and returns its RealtimeCallSummaryResponse (end reason, duration, token usage and optional estimated cost), including for a call the runtime already ended. Audio flows directly between the client and the provider, while the runtime applies the agent's instructions and executes its allowlisted tools. Both require agent.realtime.

Documentation

• Runtime source and project catalogue
• Host APIs and configuration
• License