Universal.Anthropic.Client 3.0.0.1

Universal.Anthropic.Client

Universal.Anthropic.Client is a C# library for interacting with the Anthropic API. It provides a simple and efficient way to create messages and handle streaming responses from Anthropic's AI models.

Features

• Easy-to-use client for Anthropic API
• Support for creating messages
• Streaming support for real-time responses
• Token counting for messages before creation
• Extended thinking support
• Structured JSON output
• List available models
• Customizable API version
• Built-in error handling and deserialization

Usage

Initializing the Client

var client = new AnthropicClient("YOUR_API_KEY");

Creating a Message

var request = new MessageRequest
{
    Model = Models.ClaudeSonnet46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "Hello, how are you?")
    },
    MaxTokens = 8192
};

var response = await client.CreateMessageAsync(request);
Console.WriteLine(response.Content[0].Text);

Streaming a Message

var streamingRequest = new MessageRequest
{
    Model = Models.ClaudeSonnet46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "Tell me a story about a brave knight.")
    },
    Stream = true,
    MaxTokens = 8192
};

var streamingResponse = client.CreateMessageStreamingResponse(streamingRequest);

streamingResponse.Updated += (sender, args) =>
{
    Console.WriteLine("Response updated: " + streamingResponse.Value.Content);
};

await streamingResponse.Task; // Wait for completion

Counting Message Tokens

The Token Count API allows you to count the number of tokens in a message, including tools, images, and documents, without actually creating the message. This is useful for estimating costs, validating message size limits, or optimizing your requests:

var countRequest = new CountMessageTokensRequest
{
    Model = Models.ClaudeOpus46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "What is the square root of 841, and how did you determine it?")
    },
    System = "You are an assistant for Red Marble AI. Show your detailed reasoning process when solving problems.",
    Thinking = new Thinking
    {
        Type = ThinkingTypes.Enabled,
        BudgetTokens = 2048
    }
};

var tokenCountResponse = await client.CountMessageTokensAsync(countRequest);

Console.WriteLine($"Input tokens: {tokenCountResponse.InputTokens}");

if (tokenCountResponse.InputTokens > maxAllowedTokens)
{
    Console.WriteLine("Message exceeds token limit, please reduce content.");
}
else
{
    var messageRequest = new MessageRequest
    {
        Model = countRequest.Model,
        Messages = countRequest.Messages,
        System = countRequest.System,
        Thinking = countRequest.Thinking,
        MaxTokens = 8192
    };
    
    var response = await client.CreateMessageAsync(messageRequest);
}

The CountMessageTokensResponse includes:

• InputTokens: The number of input tokens in your request
• Additional token information depending on the request structure

This method supports all the same parameters as CreateMessageAsync, including messages with text and image content, system messages, tools and tool schemas, thinking configuration, and all supported models.

Listing Available Models

The library provides a way to retrieve all available models from the Anthropic API:

var modelsResponse = await client.ListModelsAsync();

foreach (var model in modelsResponse.Data)
{
    Console.WriteLine($"ID: {model.Id}");
    Console.WriteLine($"Name: {model.DisplayName}");
    Console.WriteLine($"Created: {model.CreatedAt}");
    Console.WriteLine();
}

This functionality allows you to programmatically determine which models are available for use with the API. Models are returned with the most recently released ones listed first.

Using Tools

The Anthropic API supports the use of tools, allowing the AI to perform specific actions or retrieve information. Here's an example of how to use a tool for weather checking:

var weatherTool = new CustomTool
{
    Name = "get_weather",
    Description = "Get the current weather in a given location",
    InputSchema = new JsonSchema
    {
        Type = "object",
        Properties = new Dictionary<string, JsonSchema>()
        {
            ["location"] = new JsonSchema()
            {
                Type = "string",
                Description = "The city and state, e.g. San Francisco, CA"
            }
        },
        Required = new[] { "location" }
    }
};

var request = new MessageRequest()
{
    Model = Models.ClaudeSonnet46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "What's the weather like in San Francisco?")
    },
    System = "When asked about weather, always use the get_weather tool.",
    MaxTokens = 8192,
    Tools = new List<Tool> { weatherTool },
    ToolChoice = new AutoToolChoice()
};

var response = await client.CreateMessageAsync(request);

var toolUseBlock = response.Content.FirstOrDefault(c => c is ToolUseContentBlock) as ToolUseContentBlock;
if (toolUseBlock != null)
{
    Console.WriteLine($"Tool used: {toolUseBlock.Name}");
    Console.WriteLine($"Tool input: {toolUseBlock.Input}");
}

In this example, we define a get_weather tool with an input schema for location. The ToolChoice is set to AutoToolChoice, allowing the model to decide when to use the tool. After receiving the response, you can check if the tool was used by looking for a ToolUseContentBlock in the response content.

Using Extended Thinking

Claude supports an extended thinking feature that reveals the model's detailed reasoning process. This feature helps you understand how Claude arrives at its answers, especially for complex problems:

var request = new MessageRequest
{
    Model = Models.ClaudeSonnet46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "What's the square root of 841, and how did you determine it?")
    },
    MaxTokens = 8192,
    Thinking = new Thinking
    {
        Type = ThinkingTypes.Enabled,
        BudgetTokens = 2048
    }
};

var response = await client.CreateMessageAsync(request);

foreach (var block in response.Content)
{
    if (block is ThinkingContentBlock thinkingBlock)
    {
        Console.WriteLine("Thinking Process:");
        Console.WriteLine(thinkingBlock.Thinking);
        Console.WriteLine($"Signature: {thinkingBlock.Signature}");
    }
    else if (block is TextContentBlock textBlock)
    {
        Console.WriteLine("Final Answer:");
        Console.WriteLine(textBlock.Text);
    }
}

Structured JSON Output

You can constrain Claude's response to match a specific JSON schema using OutputConfig. This is useful for extracting structured data, building typed pipelines, or ensuring consistent response formats:

var request = new MessageRequest
{
    Model = Models.ClaudeSonnet46,
    Messages = new List<Message>
    {
        new Message(Roles.User, "Give me a person named Alice who is 30 years old.")
    },
    MaxTokens = 1024,
    OutputConfig = new OutputConfig
    {
        Format = new JsonOutputFormat
        {
            Schema = new JsonSchema
            {
                Type = "object",
                Properties = new Dictionary<string, JsonSchema>
                {
                    ["name"] = new JsonSchema { Type = "string", Description = "The person's name" },
                    ["age"] = new JsonSchema { Type = "integer", Description = "The person's age" }
                },
                Required = new[] { "name", "age" },
                AdditionalProperties = false
            }
        }
    }
};

var response = await client.CreateMessageAsync(request);
var json = (response.Content[0] as TextContentBlock).Text;

var person = JsonConvert.DeserializeObject<Dictionary<string, object>>(json);
Console.WriteLine($"Name: {person["name"]}, Age: {person["age"]}");

Note: Object schemas require AdditionalProperties = false. Array schemas only support MinItems/MaxItems values of 0 or 1.

You can also use OutputConfig to control the model's effort level independently of structured output:

OutputConfig = new OutputConfig
{
    Effort = EffortLevels.Low // "low", "medium", "high", "xhigh" (Opus 4.7/4.8 only), or "max"
}

Key Classes

• AnthropicClient: The main client for interacting with the Anthropic API.
• MessageRequest: Represents a request to create a message.
• MessageResponse: Represents the response from creating a message.
• CountMessageTokensRequest: Represents a request to count tokens in a message.
• CountMessageTokensResponse: Represents the response containing token count information.
• StreamingMessageResponse: Represents a streaming response for real-time updates.
• ListResponse<T>: Generic response for list operations, used with Model for listing available models.

Error Handling

The client throws HttpException for non-successful status codes. Make sure to handle these exceptions in your code.

Customization

You can customize the API version used by setting the AnthropicVersion property on the client:

client.AnthropicVersion = "2023-06-01";

You can also opt into betas by setting the AnthropicBeta property on the client:

client.AnthropicBeta = new[] { "beta-version-1" };

For more detailed information about the Anthropic API, please refer to the official Anthropic documentation.