アシスタントの状態

state は五つのモーションから選びます。状態は視覚的意図を伝えるだけで、マイク起動、モデル呼び出し、音声再生はしません。

状態	視覚的意図	典型的なアプリの状況
`idle`	穏やかで利用可能	次の対話の準備完了
`listening`	注意深く受け入れる	入力を収集中
`thinking`	集中して処理	要求やツール処理が進行中
`speaking`	声のような活発な動き	合成音声やストリーム音声を再生中
`asleep`	静かで暗い休息	利用不可、または意図的な休止

状態を設定する

HTML 属性を使います。


<orb-z state="listening"></orb-z>

または対応するプロパティを更新します。


import "@neongate-ai/orbz/browser";
import type { OrbzElement } from "@neongate-ai/orbz";
 
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) {
  orb.state = "thinking";
}

React と Next.js もブラウザーエントリーの導入後に同じネイティブタグを描画します。


import "@neongate-ai/orbz/browser";
import type { OrbzState } from "@neongate-ai/orbz";
 
export function AssistantPresence({ state }: { state: OrbzState }) {
  return <orb-z state={state} />;
}

state の変更はアニメーションを新しい状態のものに置き換えます。paused があれば新しい状態を表示したまま停止を維持します。

ドメイン状態は Orbz の外に保つ

実際のアシスタントには権限要求、再接続、ツール待ち、エラー復旧、割り込みなど多くの状態があります。それらはアプリに保ち、近い視覚的意図へ対応付けます。


type SessionPhase =
  | "booting"
  | "ready"
  | "capturing"
  | "transcribing"
  | "requesting"
  | "playing"
  | "offline"
  | "failed";
 
const visualState = {
  booting: "idle",
  ready: "idle",
  capturing: "listening",
  transcribing: "thinking",
  requesting: "thinking",
  playing: "speaking",
  offline: "asleep",
  failed: "idle",
} as const;

エラーの詳細は実際のテキストや操作部に表示します。色や動きだけの変更では失敗を説明できません。

無効な値と未指定の値

既定は idle です。state を削除するか型のない実行時コードで未対応値を設定すると idle に戻ります。TypeScript では OrbzState や ORBZ_STATES で未対応値を防げます。


import { ORBZ_STATES, type OrbzState } from "@neongate-ai/orbz";
 
function setState(state: OrbzState) {
  // state is one of the five documented values
}
 
for (const state of ORBZ_STATES) {
  console.log(state);
}

状態は認識できる必要がある

動きは表示であって通知ではありません。重要な状態変化を伝える際は、オーブとともに、目で確認できる状態テキストとライブリージョンを用意します。


<div role="status" aria-live="polite">
  <orb-z state="thinking"></orb-z>
  <span>Assistant is thinking</span>
</div>

動きを減らした時、停止中、非対応、見えない場合も意味が残ります。モーションとアクセシビリティへ進んでください。