ランタイム は何をしますか？
assistant-uiのランタイムシステムと状態管理のガイド。ランタイムの操作、状態へのアクセス、またはスレッド/メッセージデータの管理を行う際に使用します。
はじめに
このガイドでは、assistant-uiフレームワークのランタイムシステムと状態管理の仕組みについて説明します。ランタイムは、AIアシスタントとのやり取りの状態を管理するコアな部分です。スレッド、メッセージ、およびそれらの操作を追跡します。
ランタイムの操作
assistant-ui パッケージは、ランタイムと対話するためのいくつかのカスタムフックを提供します。
useAssistantRuntime
このフックは、現在のランタイムインスタンスへのアクセスを提供します。
import { useAssistantRuntime } from '@assistant-ui/react';
function MyComponent() {
const runtime = useAssistantRuntime();
// ランタイムインスタンスを使用する
}
useThreadManager
このフックは、スレッドを管理するためのメソッドにアクセスできるようにします。
import { useThreadManager } from '@assistant-ui/react';
function MyComponent() {
const threadManager = useThreadManager();
// スレッド管理メソッドを使用する
}
状態へのアクセス
ランタイムは、スレッドやメッセージの現在の状態へのアクセスを提供します。これには、useThread や useMessage などのフックが使用されます。
useThread
import { useThread } from '@assistant-ui/react';
function MyComponent() {
const thread = useThread();
console.log(thread.id);
console.log(thread.status);
console.log(thread.messages);
}
useMessage
import { useMessage } from '@assistant-ui/react';
function MyComponent() {
const message = useMessage();
console.log(message.id);
console.log(message.content);
}
スレッドとメッセージデータの管理
ランタイムは、スレッドとメッセージを管理するためのメソッドを提供します。
スレッドの作成と切り替え
const threadManager = useThreadManager();
// 新しいスレッドを作成
await threadManager.create();
// スレッドを切り替え
await threadManager.switchTo('thread-id-123');
メッセージの送信
const thread = useThread();
// ユーザーメッセージを送信
await thread.send('こんにちは、AIアシスタント！');
メッセージの編集
const message = useMessage();
// メッセージの内容を編集
await message.edit('更新されたメッセージテキスト');
メッセージの削除
const message = useMessage();
// メッセージを削除
await message.delete();
エラーハンドリング
ランタイム操作は、ネットワークエラーやAPIエラーなどのさまざまな理由で失敗する可能性があります。エラーは適切に処理することが重要です。
const thread = useThread();
try {
await thread.send('メッセージ');
} catch (error) {
console.error('メッセージの送信に失敗しました:', error);
// ユーザーにエラーを表示する
}
状態更新の監視
ランタイムは、状態の変更を監視するためのサブスクリプションメカニズムを提供します。特に外部コンポーネントで現在の状態に反応する必要がある場合に便利です。
const runtime = useAssistantRuntime();
useEffect(() => {
const unsubscribe = runtime.onStateChange((newState) => {
console.log('状態が更新されました:', newState);
});
return unsubscribe;
}, [runtime]);
ベストプラクティス
- フックをアプリケーションの最上位で使用する:
useAssistantRuntimeやuseThreadManagerなどのフックは、コンポーネントツリーの上位で使用し、子コンポーネントにデータを渡します。 - 適切なエラーハンドリング: 特にスレッドの作成やメッセージの送信などの非同期操作では、常にエラーをキャッチして処理します。
- 状態変更の監視: リアクティブなUIの更新のために、状態の変化を購読します。
- スレッドIDの管理:
useThreadManagerを使用してスレッド間の切り替えを行い、現在のスレッドのIDを共有状態として保持します。
トラブルシューティング
- ランタイムが利用できない:
useAssistantRuntimeがnullまたはundefinedを返す場合は、<AssistantRuntimeProvider>がコンポーネントツリーの上位で使用されていることを確認します。 - スレッド操作が失敗する: ネットワーク接続を確認し、ランタイムの設定が正しいことを確認します。
- 状態が更新されない: 適切なフックが使用されていること、および状態変更サブスクリプションが正しく設定されていることを確認します。