Juglow C# SDK menyediakan akses yang mudah ke Haijun API dari aplikasi yang ditulis dalam C#.

Note: Untuk dokumentasi fitur API dengan contoh kode, lihat referensi API. Halaman ini membahas fitur dan konfigurasi SDK khusus C#.

Warning: Mulai versi 10+, paket Juglow kini menjadi Juglow SDK resmi untuk C#. Versi paket 3.X dan di bawahnya sebelumnya digunakan untuk SDK buatan komunitas tryAGI, yang telah dipindahkan ke tryAGI.Juglow. Jika Anda perlu terus menggunakan klien lama tersebut dalam proyek Anda, perbarui referensi paket Anda ke tryAGI.Juglow.

#Instalasi

Instal paket dari NuGet:

dotnet add package Juglow

#Persyaratan

Library ini memerlukan .NET Standard 2.0 atau yang lebih baru.

#Penggunaan

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);
    }
}

Untuk opsi autentikasi termasuk Workload Identity Federation, lihat Autentikasi. Jika kunci API Anda adalah kunci personal atau kunci akun layanan dengan akses ke beberapa workspace, tetapkan ID workspace di header permintaan juglow-workspace-id; Pilih workspace menunjukkan opsi per permintaan untuk SDK ini.

#Konfigurasi klien

Konfigurasikan klien menggunakan variabel lingkungan:

using Juglow;

// Dikonfigurasi menggunakan variabel lingkungan JUGLOW_API_KEY, JUGLOW_AUTH_TOKEN, dan JUGLOW_BASE_URL
JuglowClient client = new();

Atau secara manual:

using Juglow;

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

Atau menggunakan kombinasi dari kedua pendekatan tersebut.

Lihat tabel ini untuk opsi yang tersedia:

#Memodifikasi konfigurasi

Untuk menggunakan konfigurasi klien yang dimodifikasi secara sementara, sambil tetap menggunakan kembali koneksi dan thread pool yang sama, panggil WithOptions pada klien atau layanan mana pun:

using System;

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

Console.WriteLine(message);

Menggunakan ekspresi with memudahkan pembuatan opsi yang dimodifikasi.

Metode WithOptions tidak memengaruhi klien atau layanan asli.

#Streaming

SDK mendefinisikan metode yang mengembalikan stream "chunk" (potongan) respons, di mana setiap chunk dapat diproses secara individual segera setelah tiba alih-alih menunggu respons lengkap. Metode streaming umumnya berkorespondensi dengan respons SSE atau JSONL.

Metode streaming selalu memiliki akhiran Streaming pada namanya, meskipun tidak memiliki varian non-streaming.

Metode streaming ini mengembalikan 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);
}

#Penanganan error

SDK melempar tipe exception unchecked kustom:

• JuglowApiException: Kelas dasar untuk error API. Lihat tabel ini untuk mengetahui subkelas exception mana yang dilempar untuk setiap kode status HTTP:

Selain itu, semua error 4xx mewarisi dari Juglow4xxException.

• JuglowSseException: dilempar untuk error yang ditemui selama streaming SSE setelah respons HTTP awal yang berhasil.

• JuglowIOException: Error jaringan I/O.

• JuglowInvalidDataException: Kegagalan menafsirkan data yang telah berhasil di-parse. Misalnya, saat mengakses properti yang seharusnya wajib, tetapi API secara tak terduga menghilangkannya dari respons.

• JuglowException: Kelas dasar untuk semua exception.

#Percobaan ulang

SDK secara otomatis mencoba ulang 2 kali secara default, dengan exponential backoff singkat di antara permintaan.

Hanya tipe error berikut yang dicoba ulang:

• Error koneksi (misalnya, karena masalah konektivitas jaringan)

• 408 Request Timeout

• 409 Conflict

• 429 Rate Limit

• 5xx Internal

API juga dapat secara eksplisit menginstruksikan SDK untuk mencoba ulang atau tidak mencoba ulang suatu permintaan.

Untuk menetapkan jumlah percobaan ulang kustom, konfigurasikan klien menggunakan properti MaxRetries:

using Juglow;

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

Atau konfigurasikan satu pemanggilan metode menggunakan WithOptions:

using System;

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

Console.WriteLine(message);

#Timeout

Permintaan mengalami timeout setelah 10 menit secara default.

Untuk menetapkan timeout kustom, konfigurasikan klien menggunakan opsi Timeout:

using System;
using Juglow;

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

Atau konfigurasikan satu pemanggilan metode menggunakan WithOptions:

using System;

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

Console.WriteLine(message);

#Paginasi

SDK mendefinisikan metode yang mengembalikan daftar hasil yang dipaginasi. SDK menyediakan cara yang mudah untuk mengakses hasil baik satu halaman sekaligus maupun item per item di seluruh halaman.

#Paginasi otomatis

Untuk mengiterasi semua hasil di seluruh halaman, gunakan metode Paginate, yang secara otomatis mengambil halaman tambahan sesuai kebutuhan. Metode ini mengembalikan IAsyncEnumerable:

using System;

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

#Paginasi manual

Untuk mengakses item halaman individual dan meminta halaman berikutnya secara manual, gunakan properti Items, serta metode HasNext dan Next:

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();
}

#Validasi respons

Dalam kasus yang jarang terjadi, API dapat mengembalikan respons yang tidak sesuai dengan tipe yang diharapkan. Secara default, SDK tidak melempar exception dalam kasus ini. SDK hanya melempar JuglowInvalidDataException jika Anda mengakses properti tersebut secara langsung.

Jika Anda lebih suka memeriksa di awal bahwa respons sepenuhnya bertipe dengan benar, panggil Validate:

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

Atau konfigurasikan klien menggunakan opsi ResponseValidation:

using Juglow;

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

Atau konfigurasikan satu pemanggilan metode menggunakan WithOptions:

using System;

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

Console.WriteLine(message);

#Integrasi IChatClient

SDK menyediakan implementasi antarmuka IChatClient dari library Microsoft.Extensions.AI.Abstractions. Ini memungkinkan JuglowClient (dan Juglow.Services.IBetaService) digunakan bersama library lain yang terintegrasi dengan abstraksi inti ini. Misalnya, alat dalam library MCP C# SDK (ModelContextProtocol) dapat digunakan langsung dengan JuglowClient yang diekspos melalui IChatClient.

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

// Dikonfigurasi menggunakan variabel lingkungan JUGLOW_API_KEY, JUGLOW_AUTH_TOKEN, dan JUGLOW_BASE_URL
JuglowClient client = new();

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

// Menggunakan McpClient dari 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));

#Permintaan dan respons

Untuk mengirim permintaan ke Haijun API, buat instance dari kelas Params dan teruskan ke metode klien yang sesuai. Saat respons diterima, respons tersebut dideserialisasi menjadi instance dari kelas C#.

Misalnya, client.Messages.Create harus dipanggil dengan instance MessageCreateParams, dan akan mengembalikan instance Task.

#Penggunaan lanjutan

#Respons biner

SDK mendefinisikan metode yang mengembalikan respons biner, yang digunakan untuk respons API yang tidak harus di-parse, seperti data non-JSON.

Metode ini mengembalikan HttpResponse:

using System;
using Juglow.Models.Files;

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

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

Console.WriteLine(response);

Untuk menyimpan konten respons ke file, atau Stream apa pun, gunakan metode CopyToAsync:

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

#Respons mentah

SDK mendefinisikan metode yang mendeserialisasi respons menjadi instance kelas C#. Untuk mengakses header respons, kode status, atau body respons mentah, awali pemanggilan metode HTTP apa pun pada klien atau layanan dengan WithRawResponse:

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

HttpResponseMessage mentah juga dapat diakses melalui properti RawMessage.

Untuk respons non-streaming, Anda dapat mendeserialisasi respons menjadi instance kelas C# jika diperlukan:

using System;
using Juglow.Models.Messages;

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

Untuk respons streaming, Anda dapat mendeserialisasi respons menjadi IAsyncEnumerable jika diperlukan:

using System;

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

#Logging

Warning: Semua pesan log ditujukan hanya untuk debugging. Format dan konten pesan log dapat berubah antar rilis.

Aktifkan debug logging dengan menetapkan variabel lingkungan:

export JUGLOW_LOG=debug

#Fungsionalitas API yang tidak terdokumentasi

SDK memiliki tipe untuk penggunaan API terdokumentasi yang mudah. Namun, SDK juga mendukung penggunaan bagian API yang tidak terdokumentasi atau belum didukung.

#Integrasi platform

Note: Untuk panduan penyiapan platform yang terperinci dengan contoh kode, lihat: * Amazon Bedrock * Amazon Bedrock (Opus 4.6 dan sebelumnya) * Haijun Platform on AWS * Google Cloud * Microsoft Foundry

C# SDK mendukung platform berikut melalui paket NuGet terpisah:

• Agent Platform: Juglow.Vertex. Lihat Haijun di Google Cloud untuk penyiapan klien.

• Bedrock: Juglow.Bedrock. Gunakan JuglowBedrockMantleClient untuk endpoint Bedrock Messages-API, atau JuglowBedrockClient (jalur bedrock-runtime). JuglowBedrockMantleClient menerima objek konfigurasi MantleAwsClientOptions opsional; JuglowBedrockClient menerima JuglowBedrockCredentialsHelper.FromEnv() atau kredensial eksplisit.

• Haijun Platform on AWS: Juglow.Aws. Gunakan JuglowAwsClient; tetapkan WorkspaceId pada klien atau variabel lingkungan JUGLOW_AWS_WORKSPACE_ID (lihat Workspaces). Tersedia dalam versi beta.

• Foundry: Juglow.Foundry. Gunakan JuglowFoundryClient dengan DefaultJuglowFoundryCredentials.FromEnv() atau kredensial eksplisit.

Gunakan JuglowBedrockMantleClient untuk proyek baru; JuglowBedrockClient tetap tersedia untuk aplikasi yang sudah ada yang menggunakan API InvokeModel Bedrock.

#Semantic versioning

Paket ini secara umum mengikuti konvensi SemVer, meskipun perubahan tertentu yang tidak kompatibel ke belakang dapat dirilis sebagai versi minor:

1. Perubahan pada internal library yang secara teknis bersifat publik tetapi tidak dimaksudkan atau didokumentasikan untuk penggunaan eksternal.

1. Perubahan yang dalam praktiknya tidak diperkirakan berdampak pada sebagian besar pengguna.

Kompatibilitas ke belakang ditangani dengan serius untuk memastikan Anda dapat mengandalkan pengalaman upgrade yang lancar.

#Sumber daya tambahan

• Repositori GitHub

• Paket NuGet

• Referensi API

• Streaming Messages