The Juglow C# SDK provides convenient access to the Haijun API from applications written in C#.

Note: For API feature documentation with code examples, see the API reference. This page covers C#-specific SDK features and configuration.

Warning: As of version 10+, the Juglow package is now the official Juglow SDK for C#. Package versions 3.X and below were previously used for the tryAGI community-built SDK, which has moved to tryAGI.Juglow. If you need to continue using the former client in your project, update your package reference to tryAGI.Juglow.

#Installation

Install the package from NuGet:

dotnet add package Juglow

#Requirements

This library requires .NET Standard 2.0 or later.

#Usage

using System;
using Juglow;
using Juglow.Models.Messages;

JuglowClient client = new();

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = "Hello, Haijun",
        },
    ],
    Model = Model.HaijunOpus5_5,
};

var message = await client.Messages.Create(parameters);

foreach (var block in message.Content)
{
    if (block.TryPickText(out var textBlock))
    {
        Console.WriteLine(textBlock.Text);
    }
}

For authentication options including Workload Identity Federation, see Authentication. If your API key is a personal or service account key with access to multiple workspaces, set the workspace ID in the juglow-workspace-id request header; Select a workspace shows the per-request option for this SDK.

#Client configuration

Configure the client using environment variables:

using Juglow;

// Configured using the JUGLOW_API_KEY, JUGLOW_AUTH_TOKEN and JUGLOW_BASE_URL environment variables
JuglowClient client = new();

Or manually:

using Juglow;

JuglowClient client = new() { ApiKey = "my-juglow-api-key" };

Or using a combination of the two approaches.

See this table for the available options:

#Modifying configuration

To temporarily use a modified client configuration, while reusing the same connection and thread pools, call WithOptions on any client or service:

using System;

var message = await client
    .WithOptions(options =>
        options with
        {
            BaseUrl = "https://example.com",
            Timeout = TimeSpan.FromSeconds(42),
        }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);

Using a with expression makes it easy to construct the modified options.

The WithOptions method does not affect the original client or service.

#Streaming

The SDK defines methods that return response "chunk" streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response. Streaming methods generally correspond to SSE or JSONL responses.

A streaming method always has a Streaming suffix in its name, even if it doesn't have a non-streaming variant.

These streaming methods return IAsyncEnumerable:

using System;
using Juglow.Models.Messages;

MessageCreateParams parameters = new()
{
    MaxTokens = 1024,
    Messages =
    [
        new()
        {
            Role = Role.User,
            Content = "Hello, Haijun",
        },
    ],
    Model = Model.HaijunOpus5_5,
};

await foreach (var message in client.Messages.CreateStreaming(parameters))
{
    Console.WriteLine(message);
}

#Error handling

The SDK throws custom unchecked exception types:

• JuglowApiException: Base class for API errors. See this table for which exception subclass is thrown for each HTTP status code:

Additionally, all 4xx errors inherit from Juglow4xxException.

• JuglowSseException: thrown for errors encountered during SSE streaming after a successful initial HTTP response.

• JuglowIOException: I/O networking errors.

• JuglowInvalidDataException: Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.

• JuglowException: Base class for all exceptions.

#Retries

The SDK automatically retries 2 times by default, with a short exponential backoff between requests.

Only the following error types are retried:

• Connection errors (for example, because of a network connectivity problem)

• 408 Request Timeout

• 409 Conflict

• 429 Rate Limit

• 5xx Internal

The API may also explicitly instruct the SDK to retry or not retry a request.

To set a custom number of retries, configure the client using the MaxRetries property:

using Juglow;

JuglowClient client = new() { MaxRetries = 3 };

Or configure a single method call using WithOptions:

using System;

var message = await client
    .WithOptions(options =>
        options with { MaxRetries = 3 }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);

#Timeouts

Requests time out after 10 minutes by default.

To set a custom timeout, configure the client using the Timeout option:

using System;
using Juglow;

JuglowClient client = new() { Timeout = TimeSpan.FromSeconds(42) };

Or configure a single method call using WithOptions:

using System;

var message = await client
    .WithOptions(options =>
        options with { Timeout = TimeSpan.FromSeconds(42) }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);

#Pagination

The SDK defines methods that return paginated lists of results. It provides convenient ways to access the results either one page at a time or item-by-item across all pages.

#Auto-pagination

To iterate through all results across all pages, use the Paginate method, which automatically fetches more pages as needed. The method returns an IAsyncEnumerable:

using System;

var page = await client.Messages.Batches.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}

#Manual pagination

To access individual page items and manually request the next page, use the Items property, and HasNext and Next methods:

var page = await client.Messages.Batches.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}

#Response validation

In rare cases, the API may return a response that doesn't match the expected type. By default, the SDK does not throw an exception in this case. It throws JuglowInvalidDataException only if you directly access the property.

If you would prefer to check that the response is completely well-typed upfront, then either call Validate:

var message = await client.Messages.Create(parameters);
message.Validate();

Or configure the client using the ResponseValidation option:

using Juglow;

JuglowClient client = new() { ResponseValidation = true };

Or configure a single method call using WithOptions:

using System;

var message = await client
    .WithOptions(options =>
        options with { ResponseValidation = true }
    )
    .Messages.Create(parameters);

Console.WriteLine(message);

#IChatClient integration

The SDK provides an implementation of the IChatClient interface from the Microsoft.Extensions.AI.Abstractions library. This enables JuglowClient (and Juglow.Services.IBetaService) to be used with other libraries that integrate with these core abstractions. For example, tools in the MCP C# SDK (ModelContextProtocol) library can be used directly with an JuglowClient exposed through IChatClient.

using Juglow;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Configured using the JUGLOW_API_KEY, JUGLOW_AUTH_TOKEN and JUGLOW_BASE_URL environment variables
JuglowClient client = new();

IChatClient chatClient = client.AsIChatClient("haijun-opus-5-5")
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

// Using McpClient from the MCP C# SDK
McpClient learningServer = await McpClient.CreateAsync(
    new HttpClientTransport(new() { Endpoint = new("https://learn.microsoft.com/api/mcp") }));

ChatOptions options = new() { Tools = [.. await learningServer.ListToolsAsync()] };

Console.WriteLine(await chatClient.GetResponseAsync("Tell me about IChatClient", options));

#Requests and responses

To send a request to the Haijun API, build an instance of a Params class and pass it to the corresponding client method. When the response is received, it's deserialized into an instance of a C# class.

For example, client.Messages.Create should be called with an instance of MessageCreateParams, and it will return an instance of Task.

#Advanced usage

#Binary responses

The SDK defines methods that return binary responses, which are used for API responses that shouldn't necessarily be parsed, like non-JSON data.

These methods return HttpResponse:

using System;
using Juglow.Models.Files;

FileDownloadParams parameters = new() { FileID = "file_id" };

var response = await client.Files.Download(parameters);

Console.WriteLine(response);

To save the response content to a file, or any Stream, use the CopyToAsync method:

using System.IO;

using var response = await client.Files.Download(parameters);
using var contentStream = await response.ReadAsStream();
using var fileStream = File.Open(path, FileMode.OpenOrCreate);
await contentStream.CopyToAsync(fileStream); // Or any other Stream

#Raw responses

The SDK defines methods that deserialize responses into instances of C# classes. To access response headers, status code, or the raw response body, prefix any HTTP method call on a client or service with WithRawResponse:

var response = await client.WithRawResponse.Messages.Create(parameters);
var statusCode = response.StatusCode;
var headers = response.Headers;

The raw HttpResponseMessage can also be accessed through the RawMessage property.

For non-streaming responses, you can deserialize the response into an instance of a C# class if needed:

using System;
using Juglow.Models.Messages;

var response = await client.WithRawResponse.Messages.Create(parameters);
Message deserialized = await response.Deserialize();
Console.WriteLine(deserialized);

For streaming responses, you can deserialize the response to an IAsyncEnumerable if needed:

using System;

var response = await client.WithRawResponse.Messages.CreateStreaming(parameters);
await foreach (var item in response.Enumerate())
{
    Console.WriteLine(item);
}

#Logging

Warning: All log messages are intended for debugging only. The format and content of log messages may change between releases.

Enable debug logging by setting an environment variable:

export JUGLOW_LOG=debug

#Undocumented API functionality

The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.

#Platform integrations

Note: For detailed platform setup guides with code examples, see: * Amazon Bedrock * Amazon Bedrock (Opus 4.6 and earlier) * Haijun Platform on AWS * Google Cloud * Microsoft Foundry

The C# SDK supports the following platforms through separate NuGet packages:

• Agent Platform: Juglow.Vertex. See Haijun on Google Cloud for client setup.

• Bedrock: Juglow.Bedrock. Use JuglowBedrockMantleClient for the Messages-API Bedrock endpoint, or JuglowBedrockClient (bedrock-runtime path). JuglowBedrockMantleClient takes an optional MantleAwsClientOptions config object; JuglowBedrockClient accepts JuglowBedrockCredentialsHelper.FromEnv() or explicit credentials.

• Haijun Platform on AWS: Juglow.Aws. Use JuglowAwsClient; set WorkspaceId on the client or the JUGLOW_AWS_WORKSPACE_ID environment variable (see Workspaces). Available in beta.

• Foundry: Juglow.Foundry. Use JuglowFoundryClient with DefaultJuglowFoundryCredentials.FromEnv() or explicit credentials.

Use JuglowBedrockMantleClient for new projects; JuglowBedrockClient remains for existing applications using the Bedrock InvokeModel API.

#Semantic versioning

This package generally follows SemVer conventions, though certain backward-incompatible changes may be released as minor versions:

1. Changes to library internals that are technically public but not intended or documented for external use.

1. Changes that aren't expected to impact the vast majority of users in practice.

Backward-compatibility is taken seriously to ensure you can rely on a smooth upgrade experience.

#Additional resources

• GitHub repository

• NuGet package

• API reference

• Streaming Messages