mcpField
C
copilotkit-agui

copilotkit-agui

github.com/copilotkit開発39607 回インストール21 週間前に更新
リポジトリ

copilotkit-agui について

copilotkit-aguiは、CopilotKitのAG-UIイベントプロトコルを扱うスキル資料です。エージェントのバックエンドやフレームワーク連携を構築する開発者向けに、イベント順序、ストリーミング形式、状態同期、中断と再開の流れを解説します。

主な機能

  1. 01AG-UIイベントファミリーのリファレンス
  2. 02SSEとprotobufのエンコードガイド
  3. 03バックエンド実装の手順
  4. 04状態スナップショットとJSON Patchの処理
  5. 05人間参加型の中断と再開

活用シーン

  1. 01AG-UI対応エージェントバックエンドの構築
  2. 02AbstractAgent.run()の実装
  3. 03フロントエンドイベントの欠落や形式不正の調査
  4. 04状態同期とツール呼び出しの追跡

インストール

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

$npx skills add https://github.com/copilotkit/skills --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（エージェントとユーザーのインタラクション）は、エージェントと UI 間の通信を実現する、CopilotKit のオープンなイベントベースのプロトコルです。エージェントとフロントエンド間のすべてのインタラクションは、SSE（Server-Sent Events）またはバイナリ protobuf トランスポートでストリーミングされる型付きイベントを通じて行われます。エージェントは AbstractAgent.run() を実装し、RxJS Observable<BaseEvent> を返します。クライアント SDK はイベントの適用、状態管理、メッセージ履歴を処理します。

使用する場面

  • AG-UI に対応する必要があるカスタムのエージェントバックエンドを構築する場合
  • 新しいフレームワーク統合のために AbstractAgent.run() を実装する場合
  • イベントがフロントエンドに届かない、または不正な形式で届く原因をデバッグする場合
  • イベントの順序（ライフサイクル、テキスト、ツール呼び出し、状態）を理解する場合
  • 状態同期（スナップショットと JSON Patch 差分）を扱う場合
  • 人間が介在する中断／再開フローを実装する場合
  • 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_VALUE思考過程の可視化
アクティビティACTIVITY_SNAPSHOT、ACTIVITY_DELTA構造化された進捗状況の更新
カスタムRAW、CUSTOM拡張ポイント
便利なチャンクイベント

TEXT_MESSAGE_CHUNK と TOOL_CALL_CHUNK は、クライアントの transformChunks パイプラインを通じて、開始／内容／終了の 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 対応