CasCap.AgentRuntime.Contracts 1.7.0

CasCap.AgentRuntime.Contracts

Versioned request and response DTOs for .NET 10 and .NET 11 applications calling the CasCap multi-tenant Agent Runtime HTTP API. The contracts carry execution, conversation-state and definition-administration messages without trusting caller-supplied tenant or actor identity.

Installation

dotnet package add CasCap.AgentRuntime.Contracts

The source targets net10.0 and net11.0. Applications using CasCap.AgentRuntime.Client receive it transitively. Use a stable .NET 11 SDK for source development; installed packages use their selected target's runtime.

The source also contains the browser-neutral RuntimeLoggingControls contract used by the optional logging editor, outside the versioned execution API. Its minimum is a typed enum serialized with the existing string names; it contains no credentials, provider configuration or Serilog/database dependency.

Usage

Types live in CasCap.AgentRuntime.Contracts.V1. A minimal run request is:

using CasCap.AgentRuntime.Contracts.V1;

var request = new RunAgentRequest
{
    SessionId = "conversation-example",
    Input = "Summarize the available capabilities.",
};

Send it to POST /api/v1/agents/{agentName}/runs through an authenticated HTTP client.

Version 1

RunAgentRequest carries a caller-owned session identifier, text, optional binary input with its MIME type, and one-turn session bypass. The agent name is part of the route, and tenant identity deliberately does not appear in the body: the server derives it from the authenticated request context.

RunAgentResponse returns output, definition/model identity, timing, provider usage, tool-call names, tool-produced attachments, and structured delegation/compaction events. Tool arguments and provider/host property bags are returned only when the authenticated caller explicitly enables diagnostic details. Session summaries expose sizes and message counts without raw state. SessionId accepts 1–200 characters and Input 1–100,000. BinaryContent is JSON Base64, accepts at most 20 MiB decoded, and must be paired with MimeType.

RunAgentStreamItem carries delegation and compaction events as they occur, followed by the final RunAgentResponse, so callers can update progress indicators without owning runtime execution. The streaming endpoint is POST /api/v1/agents/{agentName}/runs/stream and returns an incremental JSON array rather than Server-Sent Events.

Session-control contracts inspect and reset active state, compact history, manage named snapshots, and replace complete per-session model, instruction, and persistence overrides. They expose structured summaries rather than raw Agent Framework session JSON. AgentInstructionsResponse reports the effective instructions and whether an override supplies them.

Definition-management contracts publish immutable schema-versioned JSON documents, inspect snapshot and activation history, and activate or roll back versions separately. Tenant and actor identity never appear in request DTOs; the server derives both from authenticated claims.

EvaluateAgentDefinitionRequest accepts 1–50 scenarios, 1–10 repetitions (default 1), and a MinimumPassRate from 0 to 1 (default 1). Each scenario supplies answer expectations, required/forbidden tool names and optional fixture responses. Activation can carry this request as ActivateAgentDefinitionRequest.Evaluation; deactivation is a separate reason-bearing request.

Documentation

The current source also defines SearchKnowledgeRequest, SearchKnowledgeResponse and bounded passage/source-span DTOs for the separate agent.knowledge.search surface. Search requests cannot choose a tenant, collection or embedding profile. Matches contain reviewed text, document/generation/ chunk identities, a source hash and physical-page/Markdown-block spans, not Blob URLs. These unpublished additions support explicit retrieval; they do not automatically ground agent runs or realtime calls.

• Endpoint and permission reference
• Runtime source and project catalogue
• License