Apa itu GitHub Copilot SDK?

GitHub Copilot SDK adalah toolkit multi-platform (saat ini dalam Pratinjau Teknis) yang memungkinkan Anda menyematkan runtime agen AI ke dalam aplikasi Anda sendiri. SDK mengekspos mesin yang sama di belakang GitHub Copilot CLI sebagai antarmuka yang dapat diprogram, memberi aplikasi Anda kemampuan untuk memahami instruksi bahasa alami, merencanakan tindakan, dan memanggil alat untuk memenuhi instruksi tersebut. Anda tidak perlu membangun semua infrastruktur itu dari awal.

Mengapa menggunakan SDK untuk agen AI?

Membangun agen AI berfungsi lengkap dari bawah ke atas sangatlah kompleks. Anda perlu menangani manajemen status percakapan di seluruh giliran, memutuskan kapan harus memanggil API eksternal mana, memastikan respons AI tetap berada dalam batasan, mengelola beberapa model AI untuk tugas yang berbeda, dan menerapkan langkah-langkah keamanan. Membangun alur kerja agenik dari awal berarti Anda pada dasarnya telah membangun platform mini sebelum Anda bahkan sampai ke logika bisnis Anda.

GitHub Copilot SDK menghapus kompleksitas tersebut dengan menyediakan mesin agen yang telah dibangun dan diuji produksi. SDK menangani autentikasi, manajemen model, sesi obrolan, dan streaming. Anda fokus pada apa yang terbangun di atas blok-blok penyusun tersebut—alat-alat yang spesifik untuk domain dan logika bisnis Anda.

Gambaran umum arsitektur

GitHub Copilot SDK berkomunikasi dengan GitHub Copilot CLI, yang berjalan dalam mode server sebagai proses lokal. SDK mengelola siklus hidup proses CLI secara otomatis. Semua bahasa SDK berbagi arsitektur yang sama ini.

Arsitektur mengikuti alur ini:

Your Application → SDK Client → (JSON-RPC) → Copilot CLI (server mode)

Anda berinteraksi dengan SDK melalui pustaka klien dalam bahasa pemrograman pilihan Anda. SDK menangani protokol komunikasi, sehingga Anda dapat bekerja dengan panggilan metode yang sederhana daripada pesan mentah.

Dukungan bahasa

SDK menyediakan pustaka idiomatik untuk empat bahasa pemrograman:

Baik Anda membangun aplikasi web di TypeScript atau layanan backend di C#, Anda dapat menggabungkan kemampuan agen AI yang sama.

Fitur utama

SDK menyediakan beberapa kemampuan bawaan yang menyederhanakan pembangunan agen AI.

Perulangan agen tingkat produksi

SDK menyediakan loop eksekusi yang sudah terbukti, sama seperti yang mendukung GitHub Copilot CLI. Perulangan eksekusi ini mengelola percakapan multi-giliran, memanggil alat, dan melakukan iterasi hingga tugas selesai. Anda tidak perlu membuat kode logika perencanaan dan orkestrasi.

Orkestrasi alat

Anda dapat menentukan alat kustom yang dipanggil agen AI sesuai kebutuhan selama proses penalarannya. Ketika Anda mendaftarkan alat (seperti lookupCustomer(id)), model AI agen dapat menentukan kapan harus memanggilnya. SDK mengatur koneksi sehingga AI dapat memanggil alat Anda dengan cara yang terstruktur melalui panggilan fungsi yang sebenarnya dalam runtime, daripada menebak-nebak kode.

Di .NET, alat didefinisikan menggunakan AIFunctionFactory dari Microsoft.Extensions.AI paket. Setiap alat mencakup nama, deskripsi, skema parameter, dan fungsi handler.

Fleksibilitas beragam model

SDK tidak terkait dengan satu model AI. Ini mendukung beberapa model AI dan memungkinkan pengarahan model dinamis. Misalnya, Anda mungkin menggunakan model yang lebih cepat untuk tugas sederhana dan model yang lebih mampu untuk penalaran kompleks, dalam aplikasi yang sama.

Streaming waktu nyata

SDK mendukung respons streaming, yang berarti sebagai AI menghasilkan output, Anda dapat mengalirkannya ke aplikasi Anda. Misalnya, Anda dapat melakukan streaming token untuk menampilkan indikator pengetikan atau jawaban parsial di UI obrolan. Perilaku ini membuat pengalaman lebih interaktif dan responsif.

Autentikasi dan keamanan

SDK mendukung beberapa metode autentikasi:

• Pengguna masuk GitHub: Menggunakan kembali kredensial OAuth yang disimpan dari login CLI Copilot.
• Aplikasi OAuth GitHub: Meneruskan token pengguna dari aplikasi GitHub OAuth Anda.
• Variabel lingkungan: Menggunakan COPILOT_GITHUB_TOKEN, GH_TOKEN, atau GITHUB_TOKEN.
• Bawa kunci Anda sendiri (BYOK): Menggunakan kunci API Anda sendiri untuk penyedia seperti OpenAI, Azure AI Foundry, atau Anthropic tanpa memerlukan autentikasi GitHub.

Langganan GitHub Copilot diperlukan kecuali Anda menggunakan opsi BYOK.

Manajemen konteks

SDK secara otomatis mengelola riwayat percakapan dalam sesi. Ini melacak pesan dan output alat sebelumnya sehingga model AI memiliki konteks yang dibutuhkan untuk interaksi multi-giliran yang koheren. Untuk sesi yang panjang, SDK menyediakan fitur sesi tak terbatas yang secara otomatis memadatkan konteks ketika jendela konteks mendekati batasnya, mencegah kesalahan luapan token.

Konsep inti

Memahami konsep inti SDK membantu Anda bekerja dengannya secara efektif.

Klien

Kelas CopilotClient mengelola koneksi ke server Copilot CLI. Anda membuat satu instans klien untuk aplikasi Anda dan menggunakannya untuk membuat sesi. Klien menangani memulai dan menghentikan proses CLI, membangun saluran komunikasi, dan mengelola siklus hidup sesi.

Opsi konfigurasi termasuk AutoStart (secara otomatis memulai server CLI saat sesi pertama dibuat), LogLevel (mengontrol pengelogan verbositas), CliPath (menentukan jalur kustom ke CLI yang dapat dieksekusi), dan GithubToken (menyediakan token GitHub secara langsung alih-alih mengandalkan variabel lingkungan atau login CLI).

Session

Suatu CopilotSession mewakili satu percakapan atau konteks tugas. Setiap sesi memiliki riwayat percakapan, konfigurasi model, definisi alat, dan permintaan sistemnya sendiri. Anda membuat sesi dari klien menggunakan CreateSessionAsync, mengirim pesan ke mereka, dan menerima respons melalui model berbasis peristiwa.

Opsi konfigurasi sesi utama meliputi:

• Model: Model AI yang akan digunakan (misalnya, gpt-4.1).
• SystemMessage: Menentukan peran dan perilaku agen melalui SystemMessageConfig objek dengan Mode (Tambahkan atau Ganti) dan Content string.
• Alat: Definisi alat kustom yang dapat dipanggil agen.
• InfiniteSessions: Mengontrol pemadatan konteks otomatis melalui InfiniteSessionConfig objek. Saat diaktifkan, Anda dapat mengonfigurasi BackgroundCompactionThreshold (persentase penggunaan jendela konteks yang memicu pemadatan latar belakang) dan BufferExhaustionThreshold (persentase di mana SDK memaksa pemadatan untuk mencegah luapan token).

Tools

Alat adalah fungsi yang Anda daftarkan dalam sesi sehingga agen AI dapat memanggilnya selama proses penalaran. Setiap alat memiliki nama, deskripsi, parameter, dan fungsi handler. Ketika model AI memutuskan untuk menggunakan alat, SDK mencegat permintaan, memanggil handler Anda, dan mengumpankan hasilnya kembali ke model untuk penalaran lebih lanjut.

Di .NET, Anda menentukan alat menggunakan AIFunctionFactory.Create dari Microsoft.Extensions.AI:

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

Events

SDK menggunakan model komunikasi berbasis peristiwa. Saat Anda mengirim pesan ke sesi, SDK akan mengaktifkan peristiwa saat pemrosesan terjadi:

• AssistantMessageEvent: Model AI menghasilkan respons lengkap.
• AssistantMessageDeltaEvent: Model AI menghasilkan token respons parsial selama streaming. Properti Data.DeltaContent berisi teks inkremental, yang dapat Anda tampilkan secara real time.
• SessionIdleEvent: Sesi selesai diproses (termasuk panggilan alat apa pun).
• SessionErrorEvent: Terjadi kesalahan selama pemrosesan.
• ToolExecutionStartEvent dan ToolExecutionCompleteEvent: Perangkat telah diaktifkan.

Anda berlangganan peristiwa ini untuk menangkap respons agen dan menangani kesalahan. Untuk skenario nonstreaming, gunakan AssistantMessageEvent untuk mengumpulkan respons penuh. Untuk skenario streaming (seperti menampilkan indikator pengetikan di UI obrolan), gunakan AssistantMessageDeltaEvent untuk merender token begitu mereka tiba.

Pengait sesi

SDK menyediakan kait yang memungkinkan Anda mencegat dan memodifikasi perilaku agen di titik-titik utama:

• OnPreToolUse: Mencegat pemanggilan alat sebelum eksekusi. Handler Anda mengembalikan PermissionDecision nilai—Allow untuk melanjutkan, Deny memblokir panggilan, atau Ask meminta konfirmasi kepada pengguna.
• OnPostToolUse: Hasil alat proses setelah eksekusi, berguna untuk mencatat atau memodifikasi hasil sebelum mencapai model.
• OnUserPromptSubmitted: Mencegat dan memodifikasi permintaan pengguna sebelum memproses.
• OnErrorOccurred: Menangani kesalahan dengan mengembalikan ErrorHandling nilai—Retry untuk mencoba operasi lagi, Skip untuk melanjutkan tanpa hasil, atau Abort berhenti memproses.
• OnSessionStart: Berjalan saat sesi dimulai, berguna untuk tugas inisialisasi.
• OnSessionEnd: Berjalan saat sesi berakhir, berguna untuk pembersihan atau pengelogan.

Kait ini memungkinkan Anda menerapkan kontrol izin, pengelogan, dan pagar pembatas keamanan.

Prasyarat untuk pengembangan .NET

Untuk menggunakan GitHub Copilot SDK dalam aplikasi .NET, lingkungan Anda memerlukan:

• .NET 8.0 atau yang lebih baru.
• GitHub Copilot CLI, diinstal dan tersedia di PATH sistem Anda.
• Akun GitHub dengan langganan Copilot aktif (atau kunci API Anda sendiri untuk BYOK).
• Paket GitHub.Copilot.SDK NuGet.
• Paket Microsoft.Extensions.AI NuGet (untuk menentukan alat menggunakan AIFunctionFactory).

Ringkasan

GitHub Copilot SDK menyediakan platform canggih yang siap produksi untuk membangun agen AI di aplikasi Anda. Dengan mengabstraksi kompleksitas orkestrasi agen, integrasi alat, dan manajemen konteks, SDK memungkinkan Anda fokus menentukan kemampuan agen dan logika bisnis Anda. Dengan dukungan untuk beberapa bahasa, streaming real time, dan opsi autentikasi fleksibel, GitHub Copilot SDK adalah pilihan serbaguna untuk menambahkan fungsionalitas agen AI ke berbagai aplikasi.