mcpField
C
copilotkit-agui

copilotkit-agui

github.com/copilotkit開発38.3k2.8k 回インストール今日更新
リポジトリ

copilotkit-agui について

copilotkit-aguiは、エージェントとフロントエンド間のAG-UIイベントプロトコルを実装・調査する開発者向けスキルです。型付きイベント、状態同期、ストリーミング、人間参加型の処理を扱います。

主な機能

  1. 01AG-UIイベント群の解説
  2. 02バックエンドのイベント配信ガイド
  3. 03状態スナップショットとJSON Patchの説明
  4. 04中断・再開フローの解説
  5. 05SSEとエンコーディングの調査

活用シーン

  1. 01AG-UI対応エージェントバックエンドの構築
  2. 02AbstractAgentを使ったフレームワーク統合
  3. 03フロントエンドイベントの欠落や形式不正の調査
  4. 04状態同期や人による確認の実装

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/copilotkit/copilotkit --skill copilotkit-agui

インストール後、Claude Code で/copilotkit-aguiを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

sources.md
references/
building-agents.md
client-sdk.md
event-flow-diagrams.md
protocol-spec.md

詳細

AG-UI プロトコルスキル

概要

AG-UI（Agent-User Interaction）は、エージェントと UI 間の通信を実現する、CopilotKit のオープンなイベントベースプロトコルです。エージェントとフロントエンドのすべてのやり取りは、SSE（Server-Sent Events）またはバイナリ protobuf トランスポートを介してストリーミングされる型付きイベントで行われます。エージェントは AbstractAgent.run() を実装し、RxJS の Observable<BaseEvent> を返します。クライアント SDK はイベントの適用、状態管理、メッセージ履歴を処理します。

使用する場面

  • AG-UI を使用して通信するカスタムエージェントバックエンドを構築する場合
  • 新しいフレームワーク統合向けに AbstractAgent.run() を実装する場合
  • イベントがフロントエンドに届かない、または形式が不正な状態で届く原因をデバッグする場合
  • イベントの順序（ライフサイクル、テキスト、ツール呼び出し、状態）を理解する場合
  • 状態の同期（スナップショットと JSON Patch デルタ）を扱う場合
  • Human-in-the-loop の中断／再開フローを実装する場合
  • SSE のストリーミングやエンコードの問題をトラブルシューティングする場合

使用しない場面

  • CopilotKit の React フックやフロントエンドコンポーネントには、copilotkit-develop を使用してください
  • CopilotKit のランタイムのセットアップや設定には、copilotkit-setup を使用してください
  • フレームワーク固有の統合ガイド（LangGraph、Mastra、CrewAI）には、copilotkit-integrations を使用してください

クイックリファレンス

イベントファミリー
ファミリーイベント目的
ライフサイクルRUN_STARTED、RUN_FINISHED、RUN_ERROR、STEP_STARTED、STEP_FINISHED実行の境界と進行状況
テキストTEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_ENDストリーミングテキストメッセージ
ツール呼び出しTOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_RESULTエージェントによるツール呼び出し
状態STATE_SNAPSHOT、STATE_DELTA、MESSAGES_SNAPSHOT状態の同期
推論REASONING_START、REASONING_MESSAGE_START/CONTENT/END、REASONING_END、REASONING_ENCRYPTED_VALUEChain-of-thought の可視化
アクティビティACTIVITY_SNAPSHOT、ACTIVITY_DELTA構造化された進行状況の更新
カスタムRAW、CUSTOM拡張ポイント
便利なチャンクイベント

TEXT_MESSAGE_CHUNK と TOOL_CALL_CHUNK は、クライアントの transformChunks パイプラインを通じて、Start／Content／End の 3 つのイベントに自動展開されます。バックエンドをシンプルに実装する場合に使用してください。

SSE ワイヤーフォーマット

各イベントは、SSE の data 行として送信される JSON オブジェクトです。

data: {"type":"RUN_STARTED","threadId":"t1","runId":"r1"}\n\n
data: {"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant"}\n\n
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello"}\n\n
data: {"type":"TEXT_MESSAGE_END","messageId":"m1"}\n\n
data: {"type":"RUN_FINISHED","threadId":"t1","runId":"r1"}\n\n
パッケージ
パッケージnpm目的
@ag-ui/coreイベント、型、スキーマプロトコル定義
@ag-ui/clientAbstractAgent、HttpAgent、ミドルウェア、イベント適用クライアント SDK
@ag-ui/encoderEventEncoder（SSE + protobuf）サーバー側のエンコード

ワークフロー：AG-UI バックエンドの構築

  1. エンドポイントを定義する -- RunAgentInput の本文を含む POST を受け付け、text/event-stream を返します
  2. 入力を解析する -- リクエスト本文から threadId、runId、messages、tools、state、context を抽出します
  3. イベントを順番に送信する -- 最初に RUN_STARTED、次にコンテンツイベント、最後に RUN_FINISHED または RUN_ERROR を送信します
  4. SSE としてエンコードする -- @ag-ui/encoder の EventEncoder.encode() を使用するか、data: JSON\n\n を手動で書き込みます
  5. ツールの結果を処理する -- クライアントから TOOL_CALL_RESULT が返されます。エージェントはこれを処理して続行します

動作する完全なサンプルについては、references/building-agents.md を参照してください。

主なプロトコルルール

  • すべての実行は RUN_STARTED で開始し、RUN_FINISHED または RUN_ERROR で終了する必要があります
  • TEXT_MESSAGE_CONTENT.delta は空であってはなりません
  • ツール呼び出しイベントは toolCallId で関連付けられます
  • STATE_DELTA は RFC 6902 JSON Patch 操作を使用します
  • 複数の連続した実行がサポートされています。次の実行を開始する前に、各実行を完了する必要があります
  • メッセージは実行をまたいで蓄積されます。STATE_SNAPSHOT でリセットされない限り、状態は引き継がれます

参考資料

  • references/protocol-spec.md -- スキーマと例を含む完全なイベントタイプのリファレンス
  • references/building-agents.md -- AG-UI バックエンドの構築手順
  • references/event-flow-diagrams.md -- 一般的なフローの ASCII シーケンス図
  • references/client-sdk.md -- @ag-ui/client API リファレンス

コメント

Markdown 対応