Skip to main content

Serenity* Star .NET SDK

NuGet License: MIT

Official .NET SDK for interacting with the Serenity* Star API. This SDK provides a simple and efficient way to integrate AI capabilities into your .NET applications.

Table of Contents​

Installation​

Install the package via NuGet Package Manager:

dotnet add package SubgenAI.Serenity

Or via Package Manager Console:

Install-Package SubgenAI.Serenity

Getting Started​

This section will guide you through the initial setup and usage of the Serenity* Star SDK.

Direct Instantiation​

To directly instantiate the SerenityAIHubClient, you can use the static Create method. This requires an API key which you can obtain from your Serenity* Star account.

using SubgenAI.Serenity.Client;

var client = SerenityAIHubClient.Create("your-api-key");

Usage​

Once you have instantiated the client, you can start using it to interact with the Serenity* Star.

API Reference (SerenityAIHubClient)​

Methods​

CreateConversation​
Task<CreateConversationRes> CreateConversation(
    string agentCode,
    List<ExecuteParameter> inputParameters = null,
    int? agentVersion = null,
    int apiVersion = 2,
    CancellationToken cancellationToken = default)
Execute​
Task<AgentResult> Execute(
    string agentCode,
    List<ExecuteParameter> input = null,
    int? agentVersion = null,
    int apiVersion = 2,
    CancellationToken cancellationToken = default)

Examples​

Executing an Activity Agent​

Activity agents perform specific tasks based on the input parameters provided. Here is an example of how to execute an activity agent:

using SubgenAI.Serenity.Client;
using SubgenAI.Serenity.Models.Execute;

// Create a client instance
SerenityAIHubClient client = SerenityAIHubClient.Create("your-api-key");

// Define the agent code
string agentCode = "activityagent";

// Include input parameters (if needed)
List<ExecuteParameter> input = new List<ExecuteParameter>
{
    new ExecuteParameter("word", "dog"),
    new ExecuteParameter("channel", "MyFirstProject")
};

// Execute the agent
AgentResult response = await client.Execute(agentCode, input);
Console.WriteLine(response.Content);

Executing an Assistant Agent​

Assistant agents are designed to handle conversations. Here's how you can create a conversation and interact with an assistant agent:

using SubgenAI.Serenity.Client;
using SubgenAI.Serenity.Models.Execute;

// Create a client instance
SerenityAIHubClient client = SerenityAIHubClient.Create("your-api-key");

// Define the agent code
string agentCode = "assistantagent";

// Create a conversation
CreateConversationRes conversation = await client.CreateConversation(agentCode);

// Define the input parameters for the conversation
// The message and the chatId are always required for assistant agents
List<ExecuteParameter> input = new List<ExecuteParameter>
{
    new ExecuteParameter("chatId", conversation.ChatId),
    new ExecuteParameter("message", "Hello, how are you?"),
    new ExecuteParameter("language", "german"),
    new ExecuteParameter("channel", "MyFirstProject")
};

// Execute the agent
AgentResult response = await client.Execute(agentCode, input);
Console.WriteLine(response.Content);

// Continue the conversation with another message
input = new List<ExecuteParameter>
{
    new ExecuteParameter("chatId", conversation.ChatId),
    new ExecuteParameter("message", "Fine! what can you do?"),
    new ExecuteParameter("language", "german"),
    new ExecuteParameter("channel", "Jupyter notebook")
};

response = await client.Execute(agentCode, input);
Console.WriteLine(response.Content);

Additional Parameters​

The Execute method also accepts optional parameters:

  • agentVersion: Specify the version of the agent. If none is provided, the published version is used by default.
  • apiVersion: Specify the version of the API to use. The default is version 2.

Detailed Model Information​

CreateConversationRes​

CreateConversationRes represents the response for creating a conversation with an assistant agent. It includes:

  • ChatId: A unique identifier for the chat.
  • Content: The initial content of the conversation.
  • ConversationStarters: A list of suggested conversation starters.
  • Version: The agent's version in use.
  • UseVision: Indicates whether vision capabilities are utilized.

Example of CreateConversationRes:

{
    "chatId": "bef869ec-555e-b31d-d0b2-3a179b3d1af7",
    "content": "Hello! I'm here to help you find properties in Miami and answer your questions about investments. How may I assist you today?",
    "conversationStarters": ["Hello how are you"],
    "version": 13,
    "useVision": true
}

AgentResult​

AgentResult represents the response from executing an agent. It includes:

  • Content: The AI-generated response content.
  • JsonContent: A deserialized JSON object representation of the content, if applicable.
  • CompletionUsage: Information about token usage during the request.
  • ActionResults: Results from any skill actions performed by the agent.
  • TimeToFirstToken: The time taken to generate the first token.
  • InstanceId: The instance identifier of the agent.
  • ExecutorTaskLogs: Logs of tasks executed to complete the request, including their duration and success status.

Example of AgentResult:

{
    "content": "Hi! We currently have several apartments for sale in Miami, including options in the new Mercedes Benz Brickell development. Prices range from $1,377 for 1-bedroom units to $2,736 for 3-bedroom apartments. If you'd like more details on a specific property or need help with anything else, let me know.",
    "jsonContent": null,
    "completionUsage": {
        "completionTokens": 76,
        "promptTokens": 6848,
        "totalTokens": 6924
    },
    "actionResults": {},
    "metaAnalysis": null,
    "timeToFirstToken": null,
    "instanceId": "bef869ec-555e-b31d-d0b2-3a179b3d1af7",
    "executorTaskLogs": [
        {
            "description": "Loading configuration",
            "duration": 47,
            "success": true
        },
        {
            "description": "Validating configuration",
            "duration": 10,
            "success": true
        },
        {
            "description": "Searching relevant knowledge",
            "duration": 851,
            "success": true
        },
        {
            "description": "Calculating remaining token budget",
            "duration": 18,
            "success": true
        },
        {
            "description": "Appending context",
            "duration": 36,
            "success": true
        },
        {
            "description": "Getting AI response",
            "duration": 2025,
            "success": true
        },
        {
            "description": "Calculating prices",
            "duration": 5,
            "success": true
        },
        {
            "description": "Updating chat",
            "duration": 14,
            "success": true
        }
    ]
}

Best Practices​

  • Error Handling: Always handle exceptions such as HttpRequestException when making API calls to ensure your application can gracefully handle errors.
  • Cancellation Tokens: Use CancellationToken to manage request cancellations, especially for long-running operations.
  • Dependency Injection: Integrate the SerenityAIHubClient using dependency injection for better testability and manageability of your application.

This documentation provides a comprehensive overview of the Serenity* Star SDK, including installation, usage examples, detailed model information, and best practices. For further information, please refer to the official repository.