copilotkit-integrations

CopilotKit の統合

ライブドキュメント（MCP）

このプラグインには、CopilotKit のライブドキュメントとソースコードを検索するための search-docs および search-code ツールを提供する MCP サーバー（copilotkit-docs）が含まれています。フレームワーク固有の統合方法を調べる際に便利です。

• Claude Code： プラグインの .mcp.json によって自動設定されるため、セットアップは不要です。
• Codex： 手動での設定が必要です。手順については、copilotkit-debug スキルを参照してください。

概要

CopilotKit は AG-UI（Agent-UI）プロトコルを介して外部のエージェントフレームワークに接続します。これは、フロントエンドの CopilotKit アプリケーションとバックエンドのエージェント間の双方向通信を可能にするストリーミングプロトコルです。すべての統合で、同じアーキテクチャパターンに従います。

1. エージェントサーバー -- エージェントフレームワークを HTTP サーバーとして実行します（通常、Python では FastAPI/uvicorn、JS/TS では Express/Next.js のルートを使用します）
2. AG-UI アダプター -- フレームワーク固有のアダプターが、エージェントのネイティブインターフェイスと AG-UI ワイヤープロトコルの間を変換します
3. CopilotKit ランタイム -- Next.js のキャッチオール API ルートが CopilotRuntime を作成し、AG-UI クライアントクラスを介してエージェントに接続します。これは V2 マルチルート Hono ハンドラーでマウントされます
4. フロントエンド -- React コンポーネントは useAgent、useFrontendTool、useRenderTool、useHumanInTheLoop を使用してエージェントとやり取りします

サポート対象の統合

フレームワーク	言語	AG-UI クライアント（route.ts）	AG-UI サーバーアダプター	エージェントのポート
LangGraph（Python、セルフホスト）	Python	@copilotkit/runtime/langgraph の LangGraphHttpAgent	ag-ui-langgraph（add_langgraph_fastapi_endpoint）	8123
LangGraph（Python、LangGraph Platform）	Python	@copilotkit/runtime/langgraph の LangGraphAgent	LangGraph Platform（マネージド）	可変
LangGraph（JS）	TypeScript	@copilotkit/runtime/langgraph の LangGraphAgent	@copilotkit/sdk-js/langgraph に組み込み	8123
CrewAI Flows	Python	@ag-ui/client の HttpAgent	ag-ui-crewai（add_crewai_flow_fastapi_endpoint）	8000
CrewAI Crews	Python	@ag-ui/crewai の CrewAIAgent	ag-ui-crewai（add_crewai_crew_fastapi_endpoint）	8000
PydanticAI	Python	@ag-ui/client の HttpAgent	pydantic-ai-slim[ag-ui]（AGUIAdapter.dispatch_request()）	8000
Mastra	TypeScript	@ag-ui/mastra の MastraAgent	@ag-ui/mastra に組み込み	Next.js 開発サーバー
Google ADK	Python	@ag-ui/client の HttpAgent	ag-ui-adk（add_adk_fastapi_endpoint）	8000
LlamaIndex	Python	@ag-ui/llamaindex の LlamaIndexAgent	llama-index-protocols-ag-ui（get_ag_ui_workflow_router）	9000
Agno	Python	@ag-ui/client の HttpAgent	agno（AGUI インターフェースを備えた組み込みの AgentOS）	8000
Strands	Python	@ag-ui/client の HttpAgent	ag_ui_strands（create_strands_app）	8000
Microsoft Agent Framework（Python）	Python	@ag-ui/client の HttpAgent	agent-framework-ag-ui（add_agent_framework_fastapi_endpoint）	8000
Microsoft Agent Framework（.NET）	C#	@ag-ui/client の HttpAgent	Microsoft.Agents.AI.Hosting.AGUI.AspNetCore（MapAGUI）	8000
A2A Middleware	Python + TS	@ag-ui/a2a-middleware の A2AMiddlewareAgent	エージェントごと（複数のフレームワークが混在）	9000-9002
MCP Apps	TypeScript	MCPAppsMiddleware を備えた BuiltInAgent	N/A（BuiltInAgent 上のミドルウェア）	3108

選択の決定木

適切な統合を選ぶ際にお使いください。

Is your agent written in TypeScript/JavaScript?
  YES --> Is it a Mastra agent?
    YES --> Use Mastra integration (references/integrations/mastra.md)
    NO  --> Is it a LangGraph JS agent?
      YES --> Use LangGraph JS integration (references/integrations/langgraph.md, JS section)
      NO  --> Use BuiltInAgent with MCP Apps middleware or HttpAgent
  NO (Python or .NET) -->
    Which framework?
      LangGraph     --> references/integrations/langgraph.md
      CrewAI        --> references/integrations/crewai.md
      PydanticAI    --> references/integrations/pydantic-ai.md
      Google ADK    --> references/integrations/adk.md
      LlamaIndex    --> references/integrations/llamaindex.md
      Agno          --> references/integrations/agno.md
      Strands       --> references/integrations/strands.md
      MS Agent Fw   --> references/integrations/ms-agent-framework.md
      Multiple agents (A2A) --> references/integrations/a2a.md

AG-UI プロトコルの一般的なパターン

すべての統合で、フロントエンド側に共通するパターンがあります。

CopilotKit プロバイダー（layout.tsx）

import { CopilotKit } from "@copilotkit/react-core/v2";
import "@copilotkit/react-core/v2/styles.css";

export default function RootLayout({ children }) {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit" useSingleEndpoint={false}>
      {children}
    </CopilotKit>
  );
}

プロバイダーコンポーネントは CopilotKit（@copilotkit/react-core/v2 からインポート）です。agent prop はありません。エージェントは agentId を使ってフックごとに選択します（CopilotRuntime({ agents: { ... } }) のキーと一致します）。useSingleEndpoint={false} を指定すると、以下のキャッチオールバックエンドルートに対してマルチルートのトランスポートが固定されます。省略可能で、省略するとプロバイダーがモードを検出しますが、固定すると検出プローブをスキップできます。

API ルートのパターン（route.ts）

すべてのインテグレーションでは、V2 マルチルートの Hono ハンドラーを使って、Next.js のキャッチオール API ルート src/app/api/copilotkit/[[...slug]]/route.ts を作成します。

import {
  CopilotRuntime,
  createCopilotHonoHandler,
  InMemoryAgentRunner,
} from "@copilotkit/runtime/v2";
import { handle } from "hono/vercel";
// Import the appropriate agent class for your framework

const runtime = new CopilotRuntime({
  agents: {
    default: new SomeAgentClass({ url: "http://localhost:8000/" }),
  },
  runner: new InMemoryAgentRunner(),
});

const app = createCopilotHonoHandler({
  runtime,
  basePath: "/api/copilotkit",
});

export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);

非推奨ではないファクトリーの createCopilotHonoHandler を使用してください（createCopilotEndpoint はエイリアスです）。フロントエンドでは、agentId: "default" を指定してこのエージェントを選択します。

共有状態（useAgent）

useAgent が返すのは { agent } のみです。状態の読み取りには agent.state を、書き込みには agent.setState を使用します。

const { agent } = useAgent({ agentId: "default" });
const state = (agent.state as { proverbs: string[] } | undefined) ?? {
  proverbs: [],
};
const setState = (next: { proverbs: string[] }) => agent.setState(next);

フロントエンドツール（useFrontendTool）

import { z } from "zod";

useFrontendTool({
  name: "setThemeColor",
  parameters: z.object({
    themeColor: z.string().describe("The theme color to set."),
  }),
  handler: async ({ themeColor }) => {
    setThemeColor(themeColor);
    return `Set theme color to ${themeColor}`;
  },
});

生成 UI（useRenderTool）

import { z } from "zod";

useRenderTool(
  {
    name: "get_weather",
    parameters: z.object({ location: z.string() }),
    render: ({ parameters }) => <WeatherCard location={parameters.location} />,
  },
  [],
);

Human in the Loop（useHumanInTheLoop）

useHumanInTheLoop(
  {
    name: "go_to_moon",
    description: "Go to the moon on request.",
    render: ({ respond, status }) => (
      <MoonCard status={status} respond={respond} />
    ),
  },
  [],
);

エージェント側の状態管理

エージェント側では、共有状態の管理方法はフレームワークごとに異なりますが、プロトコルは同じです。エージェントは STATE_SNAPSHOT イベントを送信して、フロントエンドを更新します。フレームワーク固有のパターンについては、各インテグレーションガイドを参照してください。

主要なパッケージ

フロントエンド（すべてのインテグレーション）：

• @copilotkit/react-core/v2 -- プロバイダー（CopilotKit）、フック（useAgent、useFrontendTool、useRenderTool、useHumanInTheLoop）、チャットコンポーネント（CopilotChat、CopilotSidebar、CopilotPopup）。スタイル：import "@copilotkit/react-core/v2/styles.css"。
• @copilotkit/runtime/v2 -- サーバーランタイム（CopilotRuntime、createCopilotHonoHandler、InMemoryAgentRunner）

AG-UI クライアントクラス（各インテグレーションでいずれか1つを選択）：

• @copilotkit/runtime/langgraph -- LangGraphAgent、LangGraphHttpAgent
• @ag-ui/client -- HttpAgent（汎用。あらゆる AG-UI サーバーで動作）
• @ag-ui/crewai -- CrewAIAgent
• @ag-ui/mastra -- MastraAgent
• @ag-ui/llamaindex -- LlamaIndexAgent
• @ag-ui/a2a-middleware -- A2AMiddlewareAgent
• @ag-ui/mcp-apps-middleware -- MCPAppsMiddleware