KorinAI

Message Structure

Learn how to work with KorinAI's message structure for chat integration. This guide explains the core message types and their usage.

Overview

Messages are an ordered list of turns from the user and the assistant. Each message may include a parts array to represent rich content such as text or tool activity.

Key Features

  • Markdown‑capable text parts.
  • Tool invocation parts with evolving state (e.g., call → partial → result) when tools are enabled.
  • Optional metadata for correlation, auditing, and UI hints.

Message Anatomy

Every message includes:

  • id: unique identifier.
  • role: user or assistant.
  • parts: ordered content blocks.

Standard parts: text, tool-call, tool-result, reasoning. Optional multimodal parts: image, file. App‑specific extensions (e.g., source, dashboard tool-*) are described below. This guide stays high‑level and avoids repeating detailed schemas.

Roles

  • user: end‑user authored turns (inputs, file drops, instructions).
  • assistant: model/agent authored turns (answers, tool calls, citations).

Parts Overview

Parts is an ordered array of objects of type UIMessagePart. This is a union of:

  • TextUIPart — markdown-capable text from the user/assistant.

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

  • ReasoningUIPart — internal reasoning/planning text (hide by default for end users).

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

  • ToolUIPart<TOOLS> — tool activity composed of tool-call and later tool-result, matched by 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 — UI-only tool-like entries rendered by the dashboard (e.g., tool-* with states).

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

  • SourceUrlUIPart — citation referencing a URL (id, url, title).

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

  • SourceDocumentUIPart — citation referencing a document/source blob.

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

  • FileUIPart — downloadable artifact (e.g., JSON/CSV/PDF) with basic metadata.

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

  • DataUIPart<DATA_TYPES> — structured data blocks (tables, charts) for richer rendering.

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

  • StepStartUIPart — marks the beginning of a multi-step action; may carry attachments.

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

Available Built‑in Tools

Below are the built‑in tool names grouped by agent. Use these in tool-call parts (toolName) and expect corresponding tool-result parts.

  • 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

Best Practices

  • Validate structure

    • Ensure id, role, and parts are present.
    • Be liberal in what you accept; unknown part types should be ignored safely.

  • Handle tool calls and results robustly

    • Generate and persist a unique toolCallId per invocation; echo it back on the matching tool-result.
    • Redact or mask sensitive args values in the UI and logs.
    • Handle error results: display a concise message and enable safe retries when appropriate.

  • Streaming UX

    • Append text deltas incrementally for a responsive experience.
    • Keep the UI responsive during tool execution; don’t block rendering while awaiting tool-result.

  • Idempotency and retries

    • Prefer idempotent tool designs; document any side effects.
    • Use bounded retries for transient failures; avoid duplicate destructive actions.

  • Security and privacy

    • Sanitize rendered content; treat tool outputs as untrusted.
    • Avoid logging PII/secrets; prefer short diagnostics over full payloads.
    • Restrict file/command access to approved scopes; validate inputs server‑side.

  • Attachments and artifacts

    • Render experimental_attachments as non‑blocking chips or thumbnails.
    • Provide options to view/download large results outside the chat stream.

  • Telemetry and observability

    • Capture minimal, actionable traces (latency, success/error, token usage).
    • Use correlation IDs (e.g., roomId, request IDs) rather than user identifiers.

Related Topics

Next
REST API →