KorinAI

Struktur Pesan

Pelajari cara bekerja dengan struktur pesan KorinAI untuk integrasi chat. Panduan ini menjelaskan tipe pesan inti dan cara pemakaiannya.

Ringkasan

Pesan adalah daftar berurutan dari giliran user dan assistant. Setiap pesan dapat berisi array parts untuk merepresentasikan konten kaya seperti teks atau aktivitas Tools.

Fitur Utama

  • Bagian teks yang mendukung Markdown.
  • Bagian pemanggilan Tools dengan status yang berkembang (mis., call → partial → result) saat Tools diaktifkan.
  • Metadata opsional untuk korelasi, audit, dan petunjuk UI.

Anatomi Pesan

Setiap pesan mencakup:

  • id: pengenal unik.
  • role: user atau assistant.
  • parts: blok konten berurutan.

Bagian standar: text, tool-call, tool-result, reasoning. Bagian multimodal opsional: image, file. Ekstensi khusus aplikasi (mis., source, entri dashboard tool-*) dijelaskan di bawah. Panduan ini tetap tingkat tinggi dan menghindari pengulangan skema mendetail.

Peran

  • user: giliran yang ditulis pengguna (input, unggah file, instruksi).
  • assistant: giliran yang ditulis model/agen (jawaban, pemanggilan Tools, sitasi).

Gambaran Parts

parts adalah array berurutan dari objek bertipe UIMessagePart. Ini adalah gabungan dari:

  • TextUIPart — teks yang mendukung Markdown dari pengguna/asisten.

    ts
    {
  type: "text";
  text: string;
}

  • ReasoningUIPart — teks penalaran/perencanaan internal (sebaiknya disembunyikan dari pengguna akhir).

    ts
    {
  type: "reasoning";
  text: string;
}

  • ToolUIPart<TOOLS> — aktivitas Tools yang terdiri dari tool-call lalu tool-result, dipasangkan dengan toolCallId.

    ts
    {
"type": "tool-call";
"toolName": string;
"toolCallId": string;
"args": Record<string, unknown>;
}
    ts
    {
"type": "tool-result";
"toolName": string;
"toolCallId": string;
"result": unknown;
"isError"?: boolean;
}

  • DynamicToolUIPart — entri mirip Tools yang hanya untuk UI dan dirender dashboard (mis., tool-* dengan state).

    ts
    {
"type": `tool-${string}`;
"state": "input-streaming" | "input-available" | "output-available" | "output-error";
"input"?: any;
"output"?: any;
}

  • SourceUrlUIPart — sitasi yang merujuk ke URL (id, url, title).

    ts
    {
"type": "source";
"source": {
  "sourceType": "url";
  "id": string;
  "url": string;
  "title"?: string;
};
}

  • SourceDocumentUIPart — sitasi yang merujuk ke dokumen/sumber blob.

    ts
    {
  type: "source";
  source: { sourceType: "document"; id: string; title?: string };
}

  • FileUIPart — artefak yang bisa diunduh (mis., JSON/CSV/PDF) dengan metadata dasar.

    ts
    { type: "file"; name?: string; contentType?: string; url: string }

  • DataUIPart<DATA_TYPES> — blok data terstruktur (tabel, grafik) untuk render yang lebih kaya.

    ts
    {
  type: "data";
  data: unknown;
}

  • StepStartUIPart — menandai awal aksi multi‑langkah; bisa membawa lampiran.

    ts
    {
  type: "step-start";
  experimental_attachments?: Array<{ name?: string; contentType?: string; url: string }>;
}

Agent Bawaan yang Tersedia

Berikut nama Agent Bawaan yang dikelompokkan per agen. Gunakan ini di parts tool-call (toolName) dan harapkan part tool-result yang sesuai.

  • Research

    • web_search
    • web_crawl

  • Image

    • image_generation, image_editing

  • Slide

    • create_slide, edit_slide, get_slide, delete_slide, insert_slide

  • Note

    • note_structure, note_insert, note_replace, note_view

  • HTML

    • html_generate, html_insert, html_replace, html_view

  • Computer

    • file_generate, file_edit, file_read, file_search
    • terminal_run, terminal_get, terminal_send
    • git_push, git_commit, list_dir, github_pull_request

Praktik Terbaik

  • Validasi struktur

    • Pastikan id, role, dan parts ada.
    • Bersikap longgar dalam menerima; tipe part yang tidak dikenal sebaiknya diabaikan dengan aman.

  • Tangani pemanggilan Tools dan hasilnya secara andal

    • Buat dan simpan toolCallId unik per pemanggilan; kembalikan pada tool-result yang cocok.
    • Redaksi atau tutupi nilai args yang sensitif di UI dan log.
    • Tangani hasil error: tampilkan pesan ringkas dan sediakan retry aman bila cocok.

  • Streaming UX

    • Tambahkan delta text secara bertahap untuk pengalaman responsif.
    • Jaga UI tetap responsif saat Tools berjalan; jangan memblokir render menunggu tool-result.

  • Idempoten dan retry

    • Utamakan desain Tools yang idempoten; dokumentasikan efek samping.
    • Gunakan retry terbatas untuk kegagalan sementara; hindari duplikasi aksi destruktif.

  • Keamanan dan privasi

    • Sanitasi konten yang dirender; perlakukan keluaran Tools sebagai tidak tepercaya.
    • Hindari mencatat PII/rahasia; utamakan diagnostik singkat daripada payload penuh.
    • Batasi akses file/perintah ke cakupan yang disetujui; validasi input di server.

  • Lampiran dan artefak

    • Render experimental_attachments sebagai chip atau thumbnail non‑blocking.
    • Sediakan opsi untuk melihat/mengunduh hasil besar di luar alur chat.

  • Telemetri dan observabilitas

    • Tangkap jejak minimal yang bermanfaat (latensi, sukses/error, penggunaan token).
    • Gunakan ID korelasi (mis., roomId, request ID) alih‑alih identitas pengguna.

Topik Terkait

Next
REST API →