Sohbet arayüzü: client, useChat ve AG-UI

Sunucu her ajanı zaten REST ve SSE üzerinden yayınlıyor. Geriye istemci yarısı kalıyor ve burada tek bir doğru cevap yok: kimi uygulama tipli bir istemci ister, kimi zaten useChat koşar, kimi de mevcut bir AG-UI yüzeyine takılır. Üçü de aynı akışı okur.

Hepsinin paylaştığı ve baştan söylenmesi gereken bir mesele var. Dayanıklı bir tool, sonuç yerine iç sentinel dönebilir — çalıştırma onay için askıya alınmıştır ya da bir guard çağrıyı engellemiştir. Bunlar iç alanlar taşır ve bir tel sözleşmesi değildir; yani tarayıcıya asla olduğu gibi ulaşmamalıdır. Onları değiştiren maskeleme, canlı akış ile geçmiş yeniden kurulumunun paylaştığı tek bir yardımcıda durur, böylece ikisi birbirinden ayrışamaz.

GnlClient sunucunun uçlarını sarar: listAgents, run, resume (aynı runId artı approvals — askıdaki tool serbest bırakılır), async generator olarak stream, geri çağırmalarla streamTo, ayrıca journal zaman çizelgesi için listRuns ve getRun. Çerçeveden bağımsızdır; @gnldev/client/react kancaları ekler.

import { GnlClient } from '@gnldev/client';

const client = new GnlClient({
  baseUrl: 'http://localhost:3000/api',
  headers: { authorization: `Bearer ${token}` },
});

const { runId } = await client.run('support', { prompt: 'Where is my order?' });

for await (const ev of client.stream('support', { runId, prompt: 'and the refund?' })) {
  if (ev.event === 'text-delta') process.stdout.write(ev.data.text);
}

// an approval came back from the operator — same runId, the suspended tool is released
await client.resume('support', runId, { 'call-7': true });

React girişi useGnlAgent ile istemcinin kendi biriktiricisi üzerine kurulu bir useChat kancası sunar; mesaj durumu sizin için toplanır.

import { useChat, useGnlAgent } from '@gnldev/client/react';

const { messages, send, streaming } = useChat(client, 'support');

Arayüzünüz zaten AI SDK'nın useChat'ini (v5) koşuyorsa bu paket onun protokolünü konuşur. toUIMessageStreamResponse dayanıklı bir çalıştırmayı UI mesaj akışına çevirir, createChatRoute ise ucu tek satırda verir.

toUIMessages diğer yarıdır: mesaj geçmişini journal'dan yeniden kurar, yani sayfa yenilenince konuşma kaybolmaz — döküm istemci durumundan değil, gerçekte ne olduğundan yeniden üretilir. Bir kesinti data-gnl-interrupt parçası olarak yüzeye çıkar; arayüz sonuç yerine bir onay istemi göstermesi gerektiğini böyle bilir.

import { createChatRoute, toUIMessages } from '@gnldev/chat-adapter';

app.route('/chat', createChatRoute(config, { agent: 'support' }));

// restore the conversation after a reload — rebuilt from the journal
const history = await toUIMessages(journal, runId);

AG-UI, CopilotKit'in ve birkaç başka ön yüzün konuştuğu protokoldür. createAguiRoute bir AG-UI HttpAgent'ının POST edebileceği tek bir uç yayınlar; pipeAguiStream ise alt seviyedeki parçadır ve çalıştırmanın akışını AG-UI olaylarına çevirir. Paket olay tiplerini kendisi tanımlar, hiçbir @ag-ui/* bağımlılığı almaz.

import { createAguiRoute } from '@gnldev/agui';

app.route('/agui', createAguiRoute(config));
// POST /agui/agents/support/run — an AG-UI HttpAgent can consume this directly