composio

Composio

Composio を使用して AI エージェントやアプリケーションを構築するための包括的なガイドです。次のいずれかを選択してください。

• Tool Router - AI エージェント向けに、認証を自動化した分離型のセキュアな MCP セッションを作成します
• Direct Execution - 手動でツールを実行し、CRUD 操作を行う従来型のアプリを構築します

使用する場面

次のような場合に、このスキルを使用してください。

AI エージェントを構築する場合：

• 外部ツール（Gmail、Slack、GitHub など）へのアクセスが必要な、チャットベースまたは自律型のエージェントを構築する場合
• セッションごとにツールへのアクセスを分離する、マルチユーザーアプリケーションを作成する場合
• 外部サービス向けの認証フローを自動化する場合
• AI フレームワーク（Vercel AI SDK、LangChain、OpenAI Agents、Claude）と統合する場合
• MCP（Model Context Protocol）を使用して動的にツールを検出する場合
• トリガーを使用するイベント駆動型エージェントを構築する場合

従来型のアプリケーションを構築する場合：

• ツールを直接実行する CRUD アプリケーションを作成する場合
• エージェントフレームワークを使用せずに、自動化ワークフローを構築する場合
• 接続済みアカウントと認証設定を管理する場合
• 特定の認証要件を持つカスタムツールを作成する場合
• セッションを分離するマルチテナントアプリケーションを実装する場合
• 実行前後のフックとモディファイアを備えたツールを構築する場合

1. エージェントの構築

Tool Router を使用して、対話型のチャットベースエージェントや、自律的に長時間タスクを実行するエージェントを構築します。Tool Router は、ユーザーごとにツールキットやツールへのアクセス範囲を設定した、分離型の MCP セッションを作成します。

主な機能：

• ユーザーごとのセッション分離
• ツールキットとツールの動的な設定
• 認証管理の自動化
• あらゆる AI フレームワークで使用できる、MCP 互換のサーバー URL
• UI 構築に役立つ接続状態の照会
• トリガーを使用したリアルタイムのイベント処理

1.1 セッション管理と設定

エージェントのセッションを作成し、ツールを設定するための基本的なパターンです。

• ユーザー ID のベストプラクティス - セキュリティと分離性を考慮したユーザー ID の選択
• 基本的なセッションの作成 - Tool Router セッションの初期化
• セッションライフサイクルのベストプラクティス - 新しいセッションを作成する場合と再利用する場合
• セッションの設定 - ツールキット、ツール、フィルターの設定
• ネイティブツールの使用 - パフォーマンスと制御性を高めるため、ネイティブツールを優先
• フレームワークとの統合 - Vercel AI、LangChain、OpenAI Agents との接続

1.2 認証フロー

ユーザーがシームレスに利用できる認証パターンです。

• チャット内での自動認証 - チャット内での認証フローを有効化
• 手動認証 - 明示的なフローに session.authorize() を使用
• 接続管理 - manageConnections、waitForConnections、カスタムコールバック URL の設定

1.3 ツールキットの照会と UI の構築

接続 UI を構築し、ツールキットの状態を確認します。

• チャット UI の構築 - ツールキットの選択、接続管理、セッション処理に対応したチャットアプリケーションの構築
• ツールキットの状態の照会 - session.toolkits() を使用して接続を確認し、ツールキットをフィルタリングして、接続 UI を構築

1.4 イベント駆動型エージェント（トリガー）

リアルタイムのイベント処理と Webhook 統合のパターンです。

• トリガーの作成 - リアルタイムイベント用のトリガーインスタンスを設定
• イベントの購読 - リアルタイムでトリガーイベントを監視
• Webhook の検証 - 受信した Webhook ペイロードを検証して処理
• トリガーの管理 - トリガーの有効化、無効化、更新、一覧表示

2. Composio ツールを使ったアプリの構築

エージェントフレームワークを使わず、ツールを手動で実行する従来型のアプリケーションには、Composio を使用します。この方法では、ツールの実行、認証、リソース管理を完全に制御できます。

主な機能：

• 手動で制御できるツールの直接実行
• 接続済みアカウント、認証設定、ツールキットに対する CRUD 操作
• 認証機能を備えたカスタムツールの作成
• マルチテナントアプリ向けのセッション分離
• 実行前／実行後のフックとモディファイア
• トリガーを使ったイベント駆動型ワークフロー

2.1 基本操作

ツールの取得と実行に関する基本的なパターン：

• ツールの取得 - フィルターや検索を使ってツールを取得します
• ツールの直接実行 - パラメーターを指定してツールを手動で実行します
• ツールのバージョン管理 - 安定性を確保するためのバージョン固定方法

2.2 リソース管理（CRUD パターン）

認証と接続をプログラムから管理します：

• 接続済みアカウントの CRUD - 接続済みアカウントを作成、読み取り、更新、削除します
• 認証設定の管理 - 認証設定を管理します
• ツールキットの管理 - ツールキット、カテゴリー、認証要件を照会します

2.3 拡張性とカスタマイズ

カスタムツールや動作を追加して Composio を拡張します：

• カスタムツールの作成 - 単独型ツールとツールキットベースのツールを構築します
• ツールモディファイア - スキーマの変更と実行フック

2.4 イベント駆動型アプリケーション

トリガーを使ってリアクティブなアプリケーションを構築します（エージェントと共通）：

• トリガーの作成 - リアルタイムイベント用のトリガーインスタンスを設定します
• イベントの購読 - トリガーイベントをリアルタイムで受信します
• Webhook の検証 - 受信した Webhook を検証して処理します
• トリガーの管理 - トリガーの有効化、無効化、更新、一覧表示を行います

2.5 ユーザーコンテキストとマルチテナント

ユーザーコンテキストとマルチテナントの分離を管理します：

• ユーザー ID のパターン - ユーザー ID と組織 ID、共有接続と分離された接続

クイックスタートの例

Tool Router を使ったエージェントの構築

import { Composio } from '@composio/core';

const composio = new Composio();

// Create a session with Gmail tools
const session = await composio.create('user_123', {
  toolkits: ['gmail'],
  manageConnections: true
});

// Use MCP URL with any AI framework
console.log('MCP URL:', session.mcp.url);

直接実行を使ったアプリの構築

import { Composio } from '@composio/core';

const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: { github: '12082025_00' }
});

// Fetch tools
const tools = await composio.tools.get('user_123', {
  toolkits: ['github']
});

// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
  userId: 'user_123',
  arguments: { owner: 'composio', repo: 'sdk' },
});

console.log(result.data);

参考資料

Tool Router（エージェント）：

• Tool Router のドキュメント
• MCP プロトコル
• フレームワーク統合の例

直接実行（アプリ）：

• Tools API
• Connected Accounts API
• Auth Configs API
• Toolkits API
• カスタムツールガイド
• モディファイア
• 基本概念

共通：

• Triggers API
• Webhook の検証