Hevolus.XRCopilotLab.Client.Public 2.5.0

XRCopilotLab.Client.Public

XRCopilotLab.Client.Public is a .NET library designed to simplify interaction with the XRCopilot Lab Public API. It provides a client for managing topics, profiles, agents, multi-agent orchestrations, and common services in a .NET project.

Version

Current Version: 2.5.0

Features

• Topic Management: Manage topics, files, and their associated data.
• Profile Management: Handle user profiles, Knowledge Graph sync, and related configurations.
• Agent Management: Interact with agents, including chat, async chat, Knowledge Graph queries, and document comparison.
• End-user feedback (v2.2.1): submit thumbs-up / thumbs-down (+ optional comment) on individual agent or orchestrator responses (SubmitFeedbackAsync) and list feedback already saved for a conversation (GetFeedbackByConversationAsync) so chat UIs can rehydrate the "already rated" state on reload.
• Q&A pipeline tuning (v2.2.1): per-agent SearchTopK (context breadth: 3 / 15 / 30 chunks for both Azure Search and Knowledge Graph), ReasoningMode (Fast / Deep), MaxReasoningIterations, MaxReasoningSeconds, EnablePermanentMemory, plus a per-request ReasoningModeOverride on UserPrompt for chat-side Deep-thinking toggles.
• Diagnostic CompletionLog (v2.2.1): structured pipeline trace returned with every chat response — Steps + per-step Parameters, per-injection breakdowns (RagChunksInjected, KgChunksInjected, MemoriesInjected), top-level counts (RagChunkCount, KgChunkCount, MemoriesInjectedCount), and PromptTruncated info when the model context window was exceeded.
• Orchestrators (v2.2.0): List, get, validate orchestrator workflows; dispatch executions (fire-and-forget); pause and resume on user interaction; stream live progress over Server-Sent Events; poll status; cancel; manage orchestrator-scoped files.
• Common Services: Access shared utilities like voices, avatars, speech synthesis & recognition, and news.

Installation

Install the package via NuGet:

dotnet add package Hevolus.XRCopilotLab.Client.Public

Or use the NuGet Package Manager in Visual Studio.

Usage

Initialization

To use the AppClient, initialize it with your API key and optionally specify the API version:

using XRCopilotLab.Client;

// Use default API version (2025-05-01)
var client = new AppClient("your-api-key");

// Use staging environment
var client = new AppClient("your-api-key", "staging");

// Use specific API version
var client = new AppClient("your-api-key", "2025-06-01");

Accessing Services

The AppClient provides access to the following services:

• Topics: Manage topics and files.
• Profiles: Manage user profiles and Knowledge Graph.
• Agents: Interact with agents, chat, and AI features.
• Orchestrators: Run multi-agent orchestrations and manage their files.
• Common: Access voices, avatars, speech synthesis & recognition, and news.

Examples

Topic Operations

// Get all topics
var topics = await client.Topics.GetTopicsAsync("company-id", null);

// Check if topic exists
var exists = await client.Topics.CheckTopicExistsAsync("company-id", topicId: "topic-id");

// Upload a file
using var fileStream = File.OpenRead("document.pdf");
await client.Topics.UploadFileAsync(fileStream, "company-id", "topic-id", "document.pdf", FileScope.None); // FileScope.None — profile-scoped upload (the API receives the raw int value)

// Get file URL
var url = await client.Topics.GetFileUrlAsync("company-id", "topic-id", "document.pdf");

// Move a file
await client.Topics.MoveFileAsync("company-id", "topic-id", "old/path.pdf", "new/path.pdf");

Agent Chat

// Get welcome message
var welcome = await client.Agents.GetWelcomeMessageAsync("company-id", "topic-id", "agent-id", "endpoint-id", "en");

// Chat with agent (ConversationId is auto-generated if not provided)
var prompt = new UserPrompt
{
    CompanyId = "company-id",
    TopicId = "topic-id",
    AgentId = "agent-id",
    EndpointId = "endpoint-id",
    Message = "Hello, how can you help me?"
};
var response = await client.Agents.ChatAsync(prompt);

// For follow-up messages, reuse the ConversationId from the response
var followUpPrompt = new UserPrompt
{
    CompanyId = "company-id",
    TopicId = "topic-id",
    AgentId = "agent-id",
    EndpointId = "endpoint-id",
    Message = "Tell me more about that",
    ConversationId = response.ConversationId // Reuse to continue conversation
};
var followUpResponse = await client.Agents.ChatAsync(followUpPrompt);

Async Chat (Fire-and-Forget)

For long-running agent interactions, use StartChatAsync to submit the prompt and return immediately. Then poll GetConversationHistoryAsync to retrieve the response when available.

// Start async chat - returns immediately with 202 Accepted
var prompt = new UserPrompt
{
    CompanyId = "company-id",
    TopicId = "topic-id",
    AgentId = "agent-id",
    EndpointId = "endpoint-id",
    Message = "Analyze this data in detail"
};
var accepted = await client.Agents.StartChatAsync(prompt);

// Poll for the response using the returned ConversationId
History history = null;
while (history == null || !history.Messages.Any(m => m.Role == "assistant"))
{
    await Task.Delay(2000);
    history = await client.Agents.GetConversationHistoryAsync(
        accepted.CompanyId,
        accepted.TopicId,
        accepted.AgentId,
        accepted.ConversationId,
        messages: 0);
}

Orchestrator: high-level (one call) (v2.2.0)

ExecuteAndWaitAsync starts the orchestration, subscribes to its SSE event stream, prompts the user when the workflow pauses for input, and returns the final OrchestrationResult:

var result = await client.Orchestrators.ExecuteAndWaitAsync(
    companyId: "company-id",
    orchestratorId: "orchestrator-id",
    request: new OrchestrationRequest { Message = "Analyze Q3 sales" },
    interactionHandler: async (interaction, ct) => new UserInteractionResponse
    {
        RequestId = interaction.InteractionId,
        ResponseValue = "yes",
        AnswerLanguage = "en"
    },
    progressHandler: evt => Console.WriteLine($"[{evt.Seq}] {evt.EventType}"));

Console.WriteLine($"Final: {result.FinalOutput}");

Orchestrator: low-level lifecycle (v2.2.0)

For full control, drive Start → Stream → (Resume) → Cancel yourself. StartExecutionAsync and ResumeExecutionAsync return immediately with HTTP 202 + an ExecutionHandle; the actual run happens asynchronously and is observable via SSE.

// 1. Dispatch (returns 202 Accepted)
var handle = await client.Orchestrators.StartExecutionAsync(
    "company-id", "orchestrator-id",
    new OrchestrationRequest { Message = "Analyze Q3 sales" });

// 2. Stream live events (auto-reconnects on soft-close)
await foreach (var evt in client.Orchestrators.StreamExecutionAsync("company-id", handle.ExecutionId))
{
    Console.WriteLine($"{evt.EventType} (seq={evt.Seq})");

    if (evt.EventType == OrchestrationEventTypes.UserInteractionRequired)
    {
        // Pause: pull interactionId + orchestrationState from evt.Data
        var req = client.Orchestrators.ExtractInteractionRequest(evt);
        await client.Orchestrators.ResumeExecutionAsync(
            req.InteractionId, req.OrchestrationState,
            new UserInteractionResponse
            {
                RequestId = req.InteractionId,
                ResponseValue = await PromptUserAsync(req.Message)
            });
    }

    if (evt.EventType is OrchestrationEventTypes.Completed
                       or OrchestrationEventTypes.Failed
                       or OrchestrationEventTypes.Cancelled)
        break;
}

// Or poll status snapshots instead of streaming:
var status = await client.Orchestrators.GetExecutionStatusAsync("company-id", handle.ExecutionId);

// Cancel a running execution (idempotent):
await client.Orchestrators.CancelExecutionAsync("company-id", "orchestrator-id", handle.ExecutionId);

Orchestrator: file management (v2.2.0)

Each orchestration run can read files uploaded to its orchestrator-scoped storage. Set OrchestrationRequest.TempFiles = true to pass them to the workflow.

// Upload (max 100 MB; uses SAS upload above 100 MB)
using var fs = File.OpenRead("input.csv");
await client.Orchestrators.UploadFileAsync(fs, "company-id", "orchestrator-id", "input.csv", FileScope.None); // FileScope.None — the API receives the raw int value

// Read-only SAS URL (valid for ~1 hour)
var url = await client.Orchestrators.GetFileReadUrlAsync("company-id", "orchestrator-id", "input.csv");

// Delete
await client.Orchestrators.DeleteFileAsync("company-id", "orchestrator-id", "input.csv");

Feedback (v2.2.1)

End users rate individual chat responses with thumbs-up / thumbs-down (and an optional comment). The server stores each record in the AgentFeedback SQL table for the XRCopilotLab.Admin portal to consume. On conversation reload the chat UI calls GetFeedbackByConversationAsync to rehydrate the "already rated" state and avoid duplicate submissions.

using XRCopilotLab.Core.Models.Config;
using XRCopilotLab.Core.Enums;

// Submit a thumbs-up with a comment
var saved = await client.Agents.SubmitFeedbackAsync(new AgentFeedback
{
    CompanyId    = "company-id",
    TopicId      = "topic-id",
    AgentId      = "agent-id",
    EndpointId   = "endpoint-id",       // optional
    ConversationId = response.ConversationId,
    UserId       = "user-object-id",    // optional
    UserQuestion = "What's the warranty period?",
    AgentResponse = response.Message,
    Rating       = FeedbackRating.ThumbsUp,
    Comment      = "Spot-on — exactly what I needed."
});

// Rehydrate per-message thumb state when reopening a past conversation
var prior = await client.Agents.GetFeedbackByConversationAsync(
    "company-id", response.ConversationId);
foreach (var fb in prior)
{
    // Match fb.UserQuestion to the agent message in the UI and mark it as rated
}

Knowledge Graph

// Sync Knowledge Graph
await client.Profiles.SyncKnowledgeGraphAsync("company-id", "topic-id", "profile-id");

// Query Knowledge Graph
var request = new KnowledgeGraphQueryRequest
{
    CompanyId = "company-id",
    TopicId = "topic-id",
    AgentId = "agent-id",
    Query = "What are the main topics?"
};
var result = await client.Agents.QueryKnowledgeGraphAsync(request);

Common Services

// Get available voices
var voices = await client.Common.GetVoicesAsync();

// Text to speech
var speechRequest = new SpeechRequest { Text = "Hello world", Language = "en", VoiceId = "voice-id" };
var audio = await client.Common.SpeechAsync(speechRequest);

// Get avatars
var avatars = await client.Common.GetAvatarsAsync("company-id");
var avatars3D = await client.Common.Get3DAvatarsAsync("company-id");

// Get news
var news = await client.Common.GetNewsAsync();

// Speech to text (recognition)
var recognitionRequest = new SpeechRecognitionRequest
{
    AudioData = base64EncodedAudio,  // Base64-encoded audio data
    Language = "en-US",              // e.g. "en-US", "it-IT"
    Format = "audio/webm"            // e.g. "audio/webm", "audio/ogg"
};
var recognized = await client.Common.SpeechRecognitionAsync(recognitionRequest);
Console.WriteLine(recognized.Text);       // Transcribed text
Console.WriteLine(recognized.Confidence); // Confidence score 0.0–1.0

API Reference

TopicService

ProfileService

AgentService

OrchestratorService (v2.2.0)

Execution model

StartExecutionAsync and ResumeExecutionAsync return immediately with an ExecutionHandle (HTTP 202). The actual run happens asynchronously in the background. To observe progress, either subscribe to the SSE stream (StreamExecutionAsync) or poll GetExecutionStatusAsync until the document reaches a terminal state. ExecuteAndWaitAsync wraps execute + stream + interaction prompt + result extraction in a single call.

OrchestrationEvent.EventType values

For step- and agent-scoped events the SDK populates OrchestrationEvent.StepId and OrchestrationEvent.AgentId directly on the event (sourced from top-level fields on the wire frame, not from Data).

CommonService

Configuration

• API Key: Required for authentication (passed via Ocp-Apim-Subscription-Key header).
• API Version: Specify the API version directly (e.g., "2025-05-01", "staging").

Dependencies

• .NET 8.0
• Azure.Storage.Blobs
• Dapper
• Markdig

Changelog

Version 2.5.0

• Intermediate messages on OrchestrationResult: IntermediateMessages (List<string>) and IntermediateMessagesRich (List<OrchestrationIntermediateMessage>, each with Text and optional Files — AgentTaskGeneratedFile: FileName, Url, ContentType) — the messages produced by Start and SendMessage steps during the run.
• OrchestrationResult.GetEffectiveFinalOutput(): the answer the user saw. Returns FinalOutput, or — when the orchestrator ends with a SendMessage step and leaves FinalOutput empty on purpose — the text of the last intermediate message (rich first, then plain). FinalOutput itself is unchanged.
• AIEndpoint.authenticationMode (EndpointAuthenticationMode: Key = 0, ManagedIdentity = 1): whether the service reaches the endpoint with an API key or with a managed identity, in which case the endpoint has no key. Read it from Agent.Endpoints.
• Same surface as the JavaScript SDK 2.6.0 (getEffectiveFinalOutput, EndpointAuthenticationMode) and the Python SDK 2.5.0 (effective_final_output(), EndpointAuthenticationMode). All additions are backward compatible.

Version 2.2.1

• New Model Fields (Agent): SearchTopK (int? — context breadth for both Azure Search and Knowledge Graph profiles, presets 3 / 15 / 30, server cap 30), ReasoningMode (enum: Fast=0, Deep=1), MaxReasoningIterations (int?, default 5, max 10), MaxReasoningSeconds (int?, default 60, max 120), EnablePermanentMemory (bool — agent-scoped memories persisted across conversations).
• New Model Fields (UserPrompt): ReasoningModeOverride (per-request override of the agent default — populated by the chat UI "Deep thinking" toggle).
• Rewritten CompletionLog: now mirrors the full server-side pipeline diagnostics. New fields: RagChunksInjected / RagChunkCount, KgChunksInjected / KgChunkCount, MemoriesInjected / MemoriesInjectedCount, PromptTruncated. New supporting classes: RagChunkInjection, KgChunkInjection, MemoryInjection, PromptTruncationInfo. Counts are always populated; per-entry lists require EnableLogs = true on the prompt.
• Extended StepType enum: ErrorResponse, TokenManagement, InjectMemoryBlock, InjectRagChunks, InjectKgChunks, ChunkedCompletion, ChunkAggregation, SkillExecution.
• Behaviour change: SearchTopK now drives both Azure Search and Knowledge Graph retrieval. Previously the KG path was hardcoded to 10 chunks/profile — it now honours the agent's setting (default 3 when unset). Existing agents may see a small recall change on KG profiles; bump SearchTopK to 15 or 30 to restore or exceed the legacy KG breadth.
• New endpoint surface (Feedback): end-user feedback on individual agent / orchestrator chat responses is now part of the public SDK.
  • AgentService.SubmitFeedbackAsync(AgentFeedback) — POST /feedback. Persists thumbs-up / thumbs-down (and optional comment) for a single Q/A pair. Required body fields: CompanyId, TopicId, AgentId, UserQuestion, AgentResponse, Rating. Server fills Id and CreatedAt if left blank.
  • AgentService.GetFeedbackByConversationAsync(companyId, conversationId) — GET /feedback/conversation/{companyId}/{conversationId}. Returns every feedback row already saved for the conversation, ordered CreatedAt ASC. Chat UIs call this on conversation reload to mark messages that have already been rated and prevent duplicate submissions.
• New model: XRCopilotLab.Core.Models.Config.AgentFeedback — fields: Id (Guid), CompanyId, TopicId, AgentId, EndpointId?, ConversationId?, UserId?, UserQuestion, AgentResponse, Rating (FeedbackRating enum: ThumbsDown = 0, ThumbsUp = 1), Comment?, CreatedAt. Tenant-scoped on CompanyId end-to-end.
• New enum: XRCopilotLab.Core.Enums.FeedbackRating (ThumbsDown = 0, ThumbsUp = 1).

Version 2.2.0

• New Service: OrchestratorService exposing orchestrator listing, validation, fire-and-forget execution dispatch (StartExecutionAsync, returns 202 Accepted), pause/resume on user interaction, idempotent cancellation, status polling, live SSE event streaming with auto-reconnect (StreamExecutionAsync), and a one-call high-level wrapper (ExecuteAndWaitAsync) that drives the full execute → stream → prompt → result loop.
• New Methods (Orchestrators): UploadFileAsync, GetFileReadUrlAsync, DeleteFileAsync for orchestrator-scoped storage (max 100 MB; auto-switches to SAS upload above 100 MB).
• New Models: Orchestrator, OrchestratorStep, OrchestratorConnection, OrchestratorEndpoint, OrchestrationRequest, OrchestrationResult, ExecutionHandle, ExecutionStatus, OrchestrationEvent, OrchestrationEventTypes, UserInteractionRequest, UserInteractionResponse, OrchestratorValidationResult.

Version 2.1.0

• Breaking Change: Constructor now accepts apiVersion string parameter instead of staging boolean.
• Bug Fix: Fixed DeleteFileAsync not properly encoding file names with special characters.
• Bug Fix: Fixed GetFileUrlAsync route to use query parameter for file name.
• New Methods: Added CheckTopicExistsAsync, MoveFileAsync, GetFileStreamAsync, GetFileSasUrlAsync, GetFileReadUrlAsync, DownloadFolderAsBase64Async to TopicService.
• New Methods: Added GetFullWelcomeMessageAsync, UploadTempFileAsync to AgentService.
• New Methods: Added GetAvatarsAsync, Get3DAvatarsAsync, GetNewsAsync, SpeechRecognitionAsync to CommonService.
• Model Updates: Added IsDynamicAgent, ModelName, Mcps, HiddenFiles, McpServerNumber to Agent model.
• Model Updates: Added FoundryAiEndpoint to Profile model.

For the full SDK reference (data models, error handling, all examples in both .NET and JavaScript), see docs/XRCopilotLab-SDK-Documentation.md.

A2A protocol support (since v2.3.0)

XRCopilot agents can also be consumed through the A2A (Agent-to-Agent) open protocol, which makes them interoperable with platforms like Microsoft Copilot Studio, Google Vertex AI Agent Builder, and any A2A-compliant client.

The A2A endpoints are not part of this proprietary SDK — they implement the A2A v0.2.5 standard and are consumed via standard clients:

• .NET: Microsoft.Agents.A2A
• Python: a2a-py
• JavaScript: @a2a/sdk

Discovery, message/send, message/stream and tasks/get methods are supported. For setup, see docs/operations/a2a-copilot-studio-setup.md.