agentemblem

Vercel AI SDK guide

Connect AgentEmblem
to the Vercel AI SDK.

Map useChat status and message parts to an animated mark. Submitted requests show loading, reasoning shows thinking, text shows composing, and tool calls show researching.

Use a built-in circle, square, spark, or cursor without artwork, or supply a custom logo. The Markdown implementation guide includes complete recipes and API rules for coding assistants.

Install both libraries

npm install agent-emblem ai @ai-sdk/react

AI SDK support is optional. AgentEmblem does not bundle AI SDK packages. Apps with another streaming setup can control state directly.

Create an activity object

Pair the current chat status with the latest part of the latest assistant message. Reuse the useChat instance that owns your conversation; do not create a separate chat just for the indicator. The following example shows the mapping inside a chat-owning client component; keep your existing transport and message-sending setup.

"use client";

import { useChat } from "@ai-sdk/react";
import {
  AgentEmblemThinking,
  getAgentEmblemStatusCopyFromAIActivity,
} from "agent-emblem";

export function AssistantStatus({ logoSvg }: { logoSvg?: string }) {
  const { messages, status } = useChat();
  const part = messages.filter((message) => message.role === "assistant")
    .at(-1)?.parts.at(-1);
  const activity = { status, part };
  const text = getAgentEmblemStatusCopyFromAIActivity(activity);

  return (
    <AgentEmblemThinking
      preset="spark"
      source={logoSvg}
      activity={activity}
      text={text}
      label={text}
      color={{ light: "#18181b", dark: "#fafafa" }}
      size={20}
      animateVisibility
      animateMotion
      animateText
    />
  );
}

Default activity mapping

Submitted → loading

Use loading after the user submits a message and before the response starts.

Reasoning → thinking

Reasoning stream parts use the contour-based thinking state.

Text → composing

Text start, delta, and completed parts use composing.

Tools and sources → researching

Tool calls, tool results, and source parts use researching.

Show status, not private reasoning

The copy helper returns short labels such as “Thinking…” and “Using a tool…”. It never displays chain-of-thought. Only customize the labels with information your app has chosen to show.

Avoid visual flicker. Parts such as reasoning-end and text-end retain the last active state. Completion signals such as finish, abort, and chat status ready or error return the mark to idle.

Use manual state when needed

If your app has its own event model, skip activity and pass one of the seven states directly. This works with any model provider or backend. When supplied, activity takes precedence over state. Listening and talking are driven manually by your audio application's state.

<AgentEmblem
  preset="circle"
  state={toolIsRunning ? "researching" : "idle"}
  size={24}
  animateVisibility
  animateMotion
/>