Integrasi AG-UI dengan Kerangka Kerja Agen

AG-UI adalah protokol yang memungkinkan Anda membangun aplikasi agen AI berbasis web dengan fitur canggih seperti streaming real time, manajemen status, dan komponen UI interaktif. Integrasi agent Framework AG-UI menyediakan konektivitas yang mulus antara agen dan klien web Anda.

Apa itu AG-UI?

AG-UI adalah protokol standar untuk membangun antarmuka agen AI yang menyediakan:

• Hosting Agen Jarak Jauh: Menyebarkan agen AI sebagai layanan web yang dapat diakses oleh beberapa klien
• Streaming Real-time: Streaming respons agen menggunakan Server-Sent Events (SSE) untuk mendapatkan umpan balik secara langsung
• Komunikasi Standar: Format pesan yang konsisten untuk interaksi agen yang andal
• Manajemen Sesi: Mempertahankan konteks percakapan di beberapa permintaan
• Fitur Tingkat Lanjut: Persetujuan human-in-the-loop, sinkronisasi status, dan penyajian UI kustom

Kapan Menggunakan AG-UI

Pertimbangkan untuk menggunakan AG-UI saat Anda perlu:

• Membangun aplikasi web atau seluler yang berinteraksi dengan agen AI
• Menyebarkan agen sebagai layanan yang dapat diakses oleh beberapa pengguna bersamaan
• Mengalirkan respons agen secara real-time untuk memberikan umpan balik pengguna langsung
• Menerapkan alur kerja persetujuan tempat pengguna mengonfirmasi tindakan sebelum eksekusi
• Menyinkronkan status antara klien dan server untuk pengalaman interaktif
• Merender komponen UI kustom berdasarkan panggilan alat agen

Fitur yang Didukung

Integrasi AG-UI Agent Framework mendukung semua 7 fitur protokol AG-UI:

1. Obrolan Agentik: Obrolan streaming dasar dengan panggilan alat otomatis
2. Backend Tool Rendering: Alat yang dijalankan pada backend dengan hasil yang dialirkan ke klien
3. Manusia dalam Perulangan: Permintaan persetujuan fungsi untuk konfirmasi pengguna
4. Agentic Generative UI: Alat asinkron untuk operasi jangka panjang dengan pembaruan status
5. UI Generatif berbasis alat: Komponen UI kustom yang dirender berdasarkan panggilan alat
6. Status Bersama: Sinkronisasi status dua arah antara klien dan server
7. Pembaruan Status Prediktif: Alirkan argumen alat sebagai pembaruan status optimis

Membangun UI agen dengan CopilotKit

CopilotKit menyediakan komponen UI yang kaya untuk membangun antarmuka pengguna agen berdasarkan protokol AG-UI standar. CopilotKit mendukung antarmuka obrolan streaming, pemanggilan alat frontend & backend, interaksi human-in-the-loop, UI generatif, status bersama, dan banyak lagi. Anda dapat melihat contoh berbagai skenario UI agen yang didukung CopilotKit di aplikasi sampel AG-UI Dojo .

CopilotKit membantu Anda fokus pada kemampuan agen sambil memberikan pengalaman pengguna yang profesional tanpa menciptakan ulang sesuatu yang sudah ada. Untuk mempelajari selengkapnya tentang mulai menggunakan Microsoft Agent Framework dan CopilotKit, lihat dokumentasi integrasi Microsoft Agent Framework for CopilotKit .

AG-UI vs. Penggunaan Agen Langsung

Meskipun Anda dapat langsung menjalankan agen di aplikasi Anda menggunakan metode Run dan RunStreamingAsync Agent Framework, AG-UI menyediakan kemampuan tambahan.

Fitur	Penggunaan Agen Langsung	Integrasi AG-UI
Penyebaran	Disematkan dalam aplikasi	Layanan jarak jauh melalui HTTP
Akses Pengguna	Aplikasi tunggal	Beberapa klien (web, seluler)
Siaran Langsung	Iterasi asinkron dalam proses	Peristiwa Server-Sent (SSE)
Pengelolaan Status	Dikelola oleh aplikasi	Rekam jepret status tingkat protokol
Konteks Sesi	Dikelola oleh aplikasi	ID sesi yang dikelola protokol
Alur Kerja Persetujuan	Implementasi kustom	Pola middleware bawaan

Gambaran Umum Arsitektur

Integrasi AG-UI menggunakan ASP.NET Core dan mengikuti arsitektur berbasis middleware yang bersih:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  ASP.NET Core           │
│  MapAGUI("/", agent)    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AIAgent                │
│  (with Middleware)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  IChatClient            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Komponen Utama

• ASP.NET Core Endpoint: MapAGUI metode ekstensi menangani permintaan HTTP dan streaming SSE
• AIAgent: Agent Framework yang dibuat dari IChatClient atau implementasi yang disesuaikan
• Middleware Pipeline: Middleware opsional untuk persetujuan, manajemen status, dan logika kustom
• Adaptor Protokol: Mengonversi antara jenis Kerangka Kerja Agen dan peristiwa protokol AG-UI
• Klien Obrolan: klien obrolan Microsoft.Extensions.AI (Azure OpenAI, OpenAI, Ollama, dll.)

Bagaimana Agent Framework Diaplikasikan ke AG-UI

Memahami bagaimana konsep Agent Framework dipetakan ke AG-UI membantu Anda membangun integrasi yang efektif:

Konsep Kerangka Kerja Agen	AG-UI Setara	Description
AIAgent	Titik Akhir Agen	Setiap agen menjadi titik akhir HTTP
agent.Run()	Permintaan HTTP POST	Klien mengirim pesan melalui HTTP
agent.RunStreamingAsync()	Peristiwa yang Dikirim oleh Server	Respons streaming melalui SSE
AgentResponseUpdate	Peristiwa AG-UI	Dikonversi ke peristiwa protokol secara otomatis
AIFunctionFactory.Create()	Alat Perangkat Lunak Penghubung	Dijalankan di server, hasil dialirkan
ApprovalRequiredAIFunction	Manusia dalam Lingkaran	Middleware diubah menjadi protokol persetujuan
AgentSession	Manajemen Sesi	ConversationId mempertahankan konteks
ChatResponseFormat.ForJsonSchema<T>()	Cuplikan Kondisi	Output terstruktur menjadi peristiwa status

Installation

Integrasi AG-UI disertakan dalam paket hosting ASP.NET Core:

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

Paket ini mencakup semua dependensi yang diperlukan untuk integrasi AG-UI termasuk Microsoft.Extensions.AI.

Langkah Selanjutnya

Untuk mulai menggunakan integrasi AG-UI:

1. Memulai: Membangun server dan klien AG-UI pertama Anda
2. Backend Tool Rendering: Menambahkan alat fungsi ke agen Anda

Sumber Daya Tambahan

• Dokumentasi Kerangka Kerja Agen
• Dokumentasi ProtokolAG-UI
• Dokumentasi Microsoft.Extensions.AI
• Repositori GitHub Kerangka Kerja Agen

AG-UI vs. Penggunaan Agen Langsung

Meskipun Anda dapat langsung menjalankan agen di aplikasi Anda menggunakan metode run dan run(..., stream=True) Agent Framework, AG-UI menyediakan kemampuan tambahan.

Fitur	Penggunaan Agen Langsung	Integrasi AG-UI
Penyebaran	Disematkan dalam aplikasi	Layanan jarak jauh melalui HTTP
Akses Pengguna	Aplikasi tunggal	Beberapa klien (web, seluler)
Siaran Langsung	Iterasi asinkron dalam proses	Peristiwa Server-Sent (SSE)
Pengelolaan Status	Dikelola oleh aplikasi	Sinkronisasi tingkat protokol dua arah
Konteks Utas	Dikelola oleh aplikasi	ID utas yang dikelola protokol
Alur Kerja Persetujuan	Implementasi kustom	Dukungan protokol bawaan

Gambaran Umum Arsitektur

Integrasi AG-UI menggunakan arsitektur modular yang bersih:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Komponen Utama

• Titik Akhir FastAPI: Titik akhir HTTP yang menangani streaming SSE dan perutean permintaan
• AgentFrameworkAgent: Pembungkus ringan yang menyesuaikan agen Agent Framework dengan protokol AG-UI
• Orkestrator: Menangani alur eksekusi yang berbeda (default, human-in-the-loop, manajemen status)
• Event Bridge: Mengonversi peristiwa Kerangka Kerja Agen menjadi peristiwa protokol AG-UI
• Adaptor Pesan: Konversi dua arah antara format pesan AG-UI dan Agent Framework
• Strategi Konfirmasi: Strategi yang dapat diperluas untuk pesan konfirmasi khusus domain

Bagaimana Agent Framework Diaplikasikan ke AG-UI

Memahami bagaimana konsep Agent Framework dipetakan ke AG-UI membantu Anda membangun integrasi yang efektif:

Konsep Kerangka Kerja Agen	AG-UI Setara	Description
Agent	Titik Akhir Agen	Setiap agen menjadi titik akhir HTTP
agent.run()	Permintaan HTTP POST	Klien mengirim pesan melalui HTTP
agent.run(..., stream=True)	Peristiwa yang Dikirim oleh Server	Respons streaming melalui SSE
Pembaruan respons agen	Peristiwa AG-UI	TEXT_MESSAGE_CONTENT, TOOL_CALL_START, dll.
Alat fungsi (@tool)	Alat Perangkat Lunak Penghubung	Dijalankan di server, hasil dialirkan ke klien
Mode persetujuan alat	Manusia dalam Lingkaran	Permintaan/respons persetujuan melalui protokol
Riwayat percakapan	Manajemen Utas	threadId mempertahankan konteks di seluruh permintaan

Installation

Instal paket integrasi AG-UI:

pip install agent-framework-ag-ui --pre

Ini menginstal kerangka kerja agen inti dan komponen integrasi AG-UI.

Langkah Selanjutnya

Untuk mulai menggunakan integrasi AG-UI:

1. Memulai: Membangun server dan klien AG-UI pertama Anda
2. Backend Tool Rendering: Menambahkan alat fungsi ke agen Anda

Sumber Daya Tambahan

• Dokumentasi Kerangka Kerja Agen
• Dokumentasi ProtokolAG-UI
• aplikasiAG-UI Dojo - Contoh aplikasi yang menunjukkan integrasi Agent Framework
• Repositori GitHub Kerangka Kerja Agen