composio

Composio — ゲートウェイ経由の外部アプリ統合

Composio を使うと、ユーザーは 1000 以上の外部アプリ（Gmail、Slack、GitHub、Google Calendar、Notion など）を Starchild エージェントに接続できます。すべての操作は Composio ゲートウェイ（composio-gateway.fly.dev）を経由し、認証と API キー管理はそこで処理されます。

アーキテクチャ

Agent (Fly 6PN network)
    ↓  HTTP (auto-authenticated by IPv6)
Composio Gateway (composio-gateway.fly.dev)
    ↓  Composio SDK
Composio Cloud → Target API (Gmail, Slack, etc.)

• COMPOSIO_API_KEY に触れることはありません — ゲートウェイが保持します
• Composio SDK を直接呼び出すことはありません — ゲートウェイ HTTP API を使用してください
• 認証は自動です — あなたの Fly 6PN IPv6 が課金 DB を介して user_id に解決されます
• 環境変数は不要です — ゲートウェイはどのエージェントコンテナからでも常にアクセス可能です

ゲートウェイのベース URL

GATEWAY = "http://composio-gateway.flycast"

すべてのリクエストは Fly 内部ネットワーク経由の平文 HTTP（flycast）を使用します。JWT は不要です。

重要 — ゲートウェイを sc-proxy 経由にしてはいけません:

• curl（以下の例のように）または プロキシなしの素の requests / http.client を使用してください。
• このホストに対して proxied_get / proxied_post を 使用しないでください（PROTOCOL では外部 API は「常にプロキシ経由」とされていますが、flycast は文書化された例外です。core.http_client も *.flycast を自動的にバイパスします）。
• ゲートウェイに対して HTTP_PROXY / HTTPS_PROXY や curl -x を設定しないでください。
• プロキシを使用すると呼び出し元の ID が書き換えられ、ゲートウェイが誤ったユーザーを認識し、connections/execute が失敗したり、別のロッカーにヒットしたりします。

API リファレンス

1. ツールの検索（コンパクト）

タスクに適したツールスラッグを見つけます。コンパクトなツール情報（スラッグ、説明、パラメーター名のみ）を返します。適切なツールを選ぶにはこれで十分です。

curl -s -X POST $GATEWAY/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via gmail"}'

レスポンス（コンパクト）:

{
  "results": [{"primary_tool_slugs": ["GMAIL_SEND_EMAIL"], "use_case": "send email", ...}],
  "tool_schemas": {
    "GMAIL_SEND_EMAIL": {
      "tool_slug": "GMAIL_SEND_EMAIL",
      "toolkit": "gmail",
      "description": "Send an email...",
      "parameters": ["to", "subject", "body", "cc", "bcc"],
      "required": ["to", "subject", "body"]
    }
  },
  "toolkit_connection_statuses": [...]
}

2. ツールスキーマの取得（完全版）

特定のツールの完全なパラメーター定義（型、説明、enum、デフォルト値）を取得します。正確なパラメーター形式が必要な場合は、検索の後にこれを使用してください。

curl -s -X POST $GATEWAY/internal/tool_schema \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLECALENDAR_EVENTS_LIST"}'

レスポンス:

{
  "data": {
    "tool_slug": "GOOGLECALENDAR_EVENTS_LIST",
    "description": "Returns events on the specified calendar.",
    "input_parameters": {
      "properties": {
        "timeMin": {"type": "string", "description": "RFC3339 timestamp..."},
        "timeMax": {"type": "string", "description": "RFC3339 timestamp..."},
        "calendarId": {"type": "string", "default": "primary"}
      },
      "required": ["calendarId"]
    }
  },
  "error": null
}

3. ツールの実行

Composio ツールを実行します。キー名は params ではなく arguments です。

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "[email protected]", "subject": "Hi", "body": "Hello!"}}'

成功時:

{"data": {"messages": [...]}, "error": null}

失敗時 — 自己修正できるように tool_schema が含まれます:

{
  "data": null,
  "error": "Missing required parameter: calendarId",
  "tool_schema": {
    "tool_slug": "GOOGLECALENDAR_EVENTS_LIST",
    "description": "...",
    "input_parameters": {"properties": {...}, "required": [...]}
  }
}

4. ユーザーの接続一覧の取得（および OAuth 完了の確認）

# Optional toolkit filter: oauth_completed_active only turns true
# when that toolkit status is ACTIVE.
curl -s "$GATEWAY/internal/connections?toolkit=gmail"

レスポンスに含まれるもの:

• connections: 現在の重複排除済み接続一覧
• oauth_completed_active: ブール値。OAuth の完了が ACTIVE として観測された場合のみ true

キャッシュの無効化は ACTIVE が観測された後にのみトリガーされ、composio-gateway 自身のインスタンスではなく、ユーザーのインスタンス（fly-force-instance-id=<user_mapping の user container_id>）を対象とします。

5. 新しい接続の開始

curl -s -X POST $GATEWAY/api/connect \
  -H "Content-Type: application/json" \
  -d '{"toolkit": "gmail"}'

ユーザーが OAuth を完了するための connect_url を返します。

ゼロフリクション接続（操作を行う際は必須）

ユーザーが外部アプリで操作を実行したい場合（メールの送信/閲覧、カレンダーイベントの作成、GitHub issue の作成、投稿など）で、そのアプリがまだ接続されていない場合にのみトリガーしてください。

純粋な Q&A / 説明（「Gmail とは何ですか?」「Calendar はどう動作しますか?」）ではトリガーしないでください。

1. 接続チェック、空のリスト、OAuth の仕組みを説明しないでください。また「接続しましょうか?」と尋ねないでください。
2. Web の場合（アクティブな SSE セッション）: 1 つの主要なツールキットに対して組み込みツールを呼び出します:

   frontend_action(action_type="composio_connect", toolkit="gmail")
   

   任意: display_name="Gmail"、title=...、description=...。 正しい小文字のツールキットスラッグを使用してください。connect_url の Markdown リンクを貼り付けないでください — フロントエンドは action_request から Connect カードをレンダリングします。
3. 表示される返信: 接続後に何を行うかについての短い 1 行（絵文字の装飾や認証 URL はなし）。
4. ユーザーが OAuth / 完了を終えるまで停止して待機し、その後で元のタスクを続行します。
5. 最初にユーザーを Connections ページを探し回るように誘導しないでください。
6. フォールバック（SSE なし / 非 Web チャネル、または frontend_action が失敗した場合）:

   curl -s -X POST $GATEWAY/api/connect \
     -H "Content-Type: application/json" \
     -d '{"toolkit": "gmail"}'
   

   その後、connect_url をそのままプレーンテキストで提示します（Markdown カードのソフトマッチは依然として不要です）。 それも失敗した場合は、短い 1 行でその旨を伝えて停止してください — 代わりのセットアップフローをでっち上げないでください。

6. 切断

curl -s -X DELETE $GATEWAY/api/connections/{connection_id}

Instagram 投稿（重要なスラッグマッピング）

Composio 検索は、この環境では実行できないレガシーな Instagram スラッグを返すことがあります。 Instagram に投稿する場合は、以下の動作するスラッグを使用してください:

1. 下書きコンテナを作成:

• INSTAGRAM_CREATE_MEDIA_CONTAINER
• 必須: ig_user_id
• 写真の一般的な引数: {"ig_user_id":"...","image_url":"https://...","content_type":"photo","caption":"..."}

2. 下書きを公開:

• INSTAGRAM_CREATE_POST
• 必須: ig_user_id、creation_id

2 ステップのフロー:

• INSTAGRAM_CREATE_MEDIA_CONTAINER を実行 → data.data.id を creation_id として読み取る
• その creation_id を指定して INSTAGRAM_CREATE_POST を実行する

ヒント: /internal/search が INSTAGRAM_POST_IG_USER_MEDIA または INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH を提案しても、実行時に「Tool ... not found」が返される場合は、上記の 2 つのスラッグに切り替えてください。

Browserbase — ハイブリッドワークフロー（セッション管理 + Playwright CDP）

Composio の Browserbase ツールは、セッションのライフサイクル（開く/閉じる/一覧表示）のみを管理します。Web ページを操作することはできません。

実際にブラウザを操作する（ナビゲート、クリック、フォーム入力、データのスクレイピング）には、Playwright の connect_over_cdp を使用してセッションの WebSocket URL に接続します。

ステップ 1: Composio 経由で Browserbase セッションを作成する

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "BROWSERBASE_TOOL_SESSIONS_CREATE", "arguments": {"projectId": "YOUR_PROJECT_ID"}}'

レスポンスには id（session_id）、status、およびタイムスタンプが含まれます。

ステップ 2: CDP WebSocket URL を構築する

import os
session_id = "<session_id from step 1>"
api_key = os.environ.get("BROWSERBASE_API_KEY")  # stored in workspace/.env
cdp_url = f"wss://connect.browserbase.com?apiKey={api_key}&sessionId={session_id}"

ステップ 3: Playwright でブラウザを操作する

from playwright.async_api import async_playwright

async with async_playwright() as p:
    browser = await p.chromium.connect_over_cdp(cdp_url)
    page = await browser.new_page()
    await page.goto("https://example.com")

    # Click, fill, screenshot — full Playwright API
    await page.click("button.submit")
    await page.fill("input[name='email']", "[email protected]")
    await page.screenshot(path="result.png")

    content = await page.content()

ステップ 4: セッションを削除する（重要 — 課金を停止します）

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "BROWSERBASE_TOOL_SESSIONS_DELETE", "arguments": {"id": "YOUR_SESSION_ID"}}'

主要な概念

項目	詳細
Composio の役割	セッションのライフサイクルのみ — セッションの作成、一覧表示、削除
Playwright の役割	ページ操作 — ナビゲート、クリック、入力、スクレイピング、スクリーンショット
メモリコスト	ローカルで約 30〜50MB（Playwright クライアントのみ）。Chromium は Browserbase のサーバー上で実行されます
検出回避	Browserbase がサーバー側で処理します — フィンガープリントのマスキング、captcha の解決、Cloudflare のバイパス。Playwright クライアントは特別な処理を行いません。
課金	分単位（切り上げ）。完了したら必ずセッションを削除してください。

完全なサンプルスクリプト（作成 → 操作 → 削除）

#!/usr/bin/env python3
"""Browserbase: create session → control with Playwright → clean up."""
import asyncio, os, requests
from playwright.async_api import async_playwright

GATEWAY = "http://composio-gateway.flycast"
PROJECT_ID = os.environ.get("BROWSERBASE_PROJECT_ID")

async def main():
    # 1. Create session via Composio
    resp = requests.post(f"{GATEWAY}/internal/execute", json={
        "tool": "BROWSERBASE_TOOL_SESSIONS_CREATE",
        "arguments": {"projectId": PROJECT_ID}
    }).json()
    session_id = resp["data"]["id"]
    print(f"Session created: {session_id}")

    try:
        # 2. Connect via CDP
        api_key = os.environ["BROWSERBASE_API_KEY"]
        cdp_url = f"wss://connect.browserbase.com?apiKey={api_key}&sessionId={session_id}"

        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(cdp_url)
            page = await browser.new_page()
            await page.goto("https://example.com")
            title = await page.title()
            print(f"Page title: {title}")
            await browser.close()

    finally:
        # 3. Always delete session to stop billing
        requests.post(f"{GATEWAY}/internal/execute", json={
            "tool": "BROWSERBASE_TOOL_SESSIONS_DELETE",
            "arguments": {"id": session_id}
        })
        print("Session deleted")

asyncio.run(main())

Composio 経由で利用可能な Browserbase ツール

ツールスラッグ	目的	主要な引数
BROWSERBASE_TOOL_SESSIONS_CREATE	ブラウザセッションを作成する	projectId
BROWSERBASE_TOOL_SESSIONS_DELETE	セッションを削除する	id
BROWSERBASE_TOOL_SESSIONS_GET	セッション情報を取得する	id
BROWSERBASE_TOOL_SESSIONS_LIST	すべてのセッションを一覧表示する	（なし）
BROWSERBASE_TOOL_SESSIONS_GET_DEBUG_INFO	デバッグ情報を取得する	id
BROWSERBASE_TOOL_SESSIONS_STOP	セッションを停止する	id
BROWSERBASE_TOOL_CONTEXTS_CREATE	永続コンテキストを作成する	projectId
BROWSERBASE_TOOL_CONTEXTS_DELETE	コンテキストを削除する	id
BROWSERBASE_TOOL_CONTEXTS_GET	コンテキスト情報を取得する	id
BROWSERBASE_TOOL_CONTEXTS_LIST	コンテキストを一覧表示する	（なし）
BROWSERBASE_TOOL_CONTEXTS_UPDATE	コンテキストのラベルを更新する	id、labels
BROWSERBASE_TOOL_UPLOADS_CREATE	セッションにファイルをアップロードする	projectId、ファイルデータ
BROWSERBASE_TOOL_UPLOADS_GET	アップロード情報を取得する	id
BROWSERBASE_TOOL_UPLOADS_LIST	アップロードを一覧表示する	（なし）
BROWSERBASE_TOOL_UPLOADS_DELETE	アップロードを削除する	id
BROWSERBASE_TOOL_DOWNLOADS_LIST	ダウンロードを一覧表示する	sessionId
BROWSERBASE_TOOL_DOWNLOADS_GET	ダウンロードを取得する	downloadId
BROWSERBASE_TOOL_DOWNLOADS_GET_STREAM	ダウンロードをストリーミングする	downloadId
BROWSERBASE_TOOL_KB_GET_KNOWLEDGE	KB の記事を取得する	id

Browserbase / Browser Tool のトラブルシューティング

Browserbase に接続できているのに実行が失敗する場合は、接続ツールキットとツールスラッグの間の名前の不一致を確認してください。

• 接続がツールキット browserbase_tool として表示されることがあります
• 検索が BROWSER_TOOL_CREATE_TASK のようなツールスラッグを返すことがあります
• 実行がそのスラッグを拒否し（Tool ... not found）、ツールキット browserbase 配下のレガシースラッグのみを解決することがあります

簡単な診断:

# 1) Health + active connections
curl -s $GATEWAY/health
curl -s $GATEWAY/internal/connections

# 2) Search browser tool slugs
curl -s -X POST $GATEWAY/internal/search \
  -H "Content-Type: application/json" \
  -d '{"query":"browserbase create task"}'

# 3) Try execute and inspect exact error
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool":"BROWSER_TOOL_CREATE_TASK","arguments":{"task":"open https://example.com"}}'

エラーが No active connection found for toolkit 'browserbase' と表示する場合、ゲートウェイはサーバー側で Browserbase のエイリアス（browser/browserbase/browserbase_tool）を正規化し、実行スラッグのバリアント（BROWSERBASE_TOOL_* ↔ BROWSER_TOOL_*）も正規化する必要があります。これにより、browserbase_tool の有効な接続で新旧どちらのクライアントも動作します。

最適なワークフロー（ツール呼び出しを最小化）

既知のツール → 直接実行（1 回の呼び出し）

以前の使用や以下の共通ツール表からツールスラッグとパラメータをすでに把握している場合は、検索を完全にスキップしてください:

curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLECALENDAR_EVENTS_LIST", "arguments": {"calendarId": "primary", "timeMin": "2026-04-02T00:00:00+08:00", "timeMax": "2026-04-09T00:00:00+08:00", "singleEvents": true, "timeZone": "Asia/Hong_Kong"}}'

未知のツール → 検索 + スキーマ + 実行（2〜3 回の呼び出し）

1. 検索（コンパクト）→ 適切なツールスラッグを選択
2. スキーマを取得（パラメータの詳細が不明な場合）→ 正確な引数の形式を把握
3. 実行 → 正しい引数で

実行が失敗した場合、エラー応答にスキーマ全体が含まれます — そのため、追加のスキーマ呼び出しなしで即座に再試行できます。

繰り返し使うためにスクリプトにまとめる

定期的なクエリには、ワンショットの Python スクリプトを書いてください:

#!/usr/bin/env python3
import sys, json, requests
from datetime import datetime, timedelta, timezone

GATEWAY = "http://composio-gateway.flycast"
days = int(sys.argv[1]) if len(sys.argv) > 1 else 7
tz_name = sys.argv[2] if len(sys.argv) > 2 else "UTC"

# ... build timeMin/timeMax ...
resp = requests.post(f"{GATEWAY}/internal/execute", json={
    "tool": "GOOGLECALENDAR_EVENTS_LIST",
    "arguments": {"calendarId": "primary", "timeMin": t_min, "timeMax": t_max,
                   "singleEvents": True, "timeZone": tz_name}
}).json()

# ... format and print ...

以降の呼び出しは bash("python3 scripts/calendar_events.py 7 Asia/Hong_Kong") だけで済みます — ツール呼び出し 1 回です。

共通ツール クイックリファレンス（これらは検索をスキップ）

📧 Gmail

ツールスラッグ	目的	主な引数
GMAIL_SEND_EMAIL	メールを送信	to, subject, body, cc, bcc
GMAIL_FETCH_EMAILS	メールを取得	max_results (int), label_ids (list), q (Gmail 検索構文)
GMAIL_CREATE_EMAIL_DRAFT	下書きを作成	to, subject, body

Gmail の使用例:

# Send email
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_SEND_EMAIL", "arguments": {"to": "[email protected]", "subject": "Hello", "body": "Hi there!"}}'

# Fetch last 5 emails
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_FETCH_EMAILS", "arguments": {"max_results": 5}}'

# Search specific emails (using Gmail search syntax)
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GMAIL_FETCH_EMAILS", "arguments": {"max_results": 10, "q": "from:github.com after:2026/03/01"}}'

Gmail の応答の解析: メールデータは data.data.messages[] にあり、各メールには id、snippet、payload.headers[] があります（From/Subject/Date はヘッダー内にあり、name で検索します）。

🐦 Twitter

ツールスラッグ	目的	主な引数
TWITTER_CREATION_OF_A_POST	投稿を作成	text（必須）, media_media_ids, reply_in_reply_to_tweet_id
TWITTER_POST_DELETE_BY_POST_ID	投稿を削除	id
TWITTER_POST_LOOKUP_BY_POST_ID	単一のツイートを取得	id, tweet_fields
TWITTER_RECENT_SEARCH	過去 7 日間を検索	query, max_results（最小 10）
TWITTER_USER_LOOKUP_ME	自分のプロフィールを取得	（パラメータなし）
TWITTER_USER_LOOKUP_BY_USERNAME	ユーザープロフィールを取得	username

Twitter の使用例:

# Post tweet
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "TWITTER_CREATION_OF_A_POST", "arguments": {"text": "Hello from Composio!"}}'

# Delete tweet
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "TWITTER_POST_DELETE_BY_POST_ID", "arguments": {"id": "2039756730192601584"}}'

Twitter の応答構造: 投稿/作成は data.data.data を返し（3 レベルのネスト）、id、text、edit_history_tweet_ids を含みます。

Twitter — 画像付き投稿（FileUploadable フロー）

重要な制約: ゲートウェイの /internal/execute は Composio v2 の actions/{slug}/execute に対する薄いラッパーです — version の固定や FileUploadable の合成はサポートしていません。Twitter のメディアアップロードツール（TWITTER_UPLOAD_MEDIA、TWITTER_UPLOAD_LARGE_MEDIA）は両方を必要とするため、ゲートウェイ経由ではなく composio_client Python SDK を直接呼び出す必要があります。

ゲートウェイは意図的に汎用的にしています — このようなツールごとのフローはすべてここ、スキル内に置いてください。

3 ステップのフロー（動作確認済み）:

import hashlib, httpx, json
from pathlib import Path
from composio_client import Composio

# COMPOSIO_API_KEY: read from /data/workspace/composio-gateway/.env
# (gateway owns the key; for skill scripts, source it the same way)
client = Composio(api_key=COMPOSIO_API_KEY)

USER_ID = f"starchild-{user_id}"   # NOTE: hyphen, not underscore
img = Path("output/images/foo.jpg")

# 1. Get presigned S3 upload URL
md5 = hashlib.md5(img.read_bytes()).hexdigest()
presigned = client.files.create_presigned_url(
    filename=img.name, md5=md5, mimetype="image/jpeg",
    tool_slug="TWITTER_UPLOAD_MEDIA", toolkit_slug="twitter",
)
# presigned.type == "new" → file is new, must PUT
# presigned.type == "existing" → cached, skip PUT
if presigned.type == "new":
    httpx.put(presigned.new_presigned_url, content=img.read_bytes(),
              headers={"Content-Type": "image/jpeg"}, timeout=60).raise_for_status()

# 2. Execute upload tool — MUST pass version="20260501_00" (or current latest)
#    media is a FileUploadable dict, NOT base64
upload_resp = client.tools.execute(
    tool_slug="TWITTER_UPLOAD_MEDIA",
    user_id=USER_ID,
    version="20260501_00",
    arguments={
        "media": {"name": img.name, "mimetype": "image/jpeg", "s3key": presigned.key},
        "media_type": "image/jpeg",
        "media_category": "tweet_image",   # or "dm_image", "subtitles"
    },
)
result = upload_resp.model_dump()
assert result["successful"], result["error"]
# Response nesting: data.data.id (NOT data.id, NOT data.media_id_string)
media_id = result["data"]["data"]["id"]

# 3. Create tweet with media_media_ids — this one is fine via gateway too
tweet_resp = client.tools.execute(
    tool_slug="TWITTER_CREATION_OF_A_POST",
    user_id=USER_ID,
    arguments={"text": "your tweet text", "media_media_ids": [str(media_id)]},
)
tweet_id = tweet_resp.model_dump()["data"]["data"]["id"]
url = f"https://x.com/i/web/status/{tweet_id}"

これが機能する理由（デバッグメモ — この知識を失わないでください）:

• GET /api/v3/tools/TWITTER_UPLOAD_MEDIA は version なしでは 404 を返します。これはデフォルトの 00000000_00 ではなく、ツールキットバージョン 20260501_00+ に存在するためです。
• client.tools.execute(version=...) は /api/v3/tools/execute/{slug} を経由し、これは version を認識します。
• ゲートウェイは execute に v2 の /api/v2/actions/{slug}/execute を使用します — v2 には version ルーティングがないため、バージョン付きツールに到達することは決してできません。このためにゲートウェイを「修正」しようとしないでください — version と FileUploadable を追加すると肥大化します。薄いままに保ってください。
• media パラメータは base64 ではなく {name, mimetype, s3key}（FileUploadable スキーマ）を期待します。base64 を渡すと次のエラーが返ります: "Input should be a valid dictionary or instance of FileUploadable on parameter media"。
• TWITTER_UPLOAD_MEDIA のファイルサイズ制限は約 5 MB です。より大きなファイル / 動画 / GIF には TWITTER_UPLOAD_LARGE_MEDIA を使用してください（チャンク化、同じフローですが追加のセグメントパラメータがあります）。

⚠️ Twitter の制限とフォールバック:

• TWITTER_RECENT_SEARCH は過去 7 日間のみを対象とし、それより古いツイートは表示されません
• TWITTER_FULL_ARCHIVE_SEARCH には Twitter API の Pro アクセスが必要で、通常の OAuth アプリでは使用できません
• ユーザーのツイート履歴を取得する場合は、プラットフォームネイティブのツール twitter_user_tweets を優先してください、7 日間に制限されません

📅 Google Calendar

ツールスラッグ	目的	主な引数
GOOGLECALENDAR_EVENTS_LIST	イベントを一覧表示	calendarId（デフォルト: "primary"）、timeMin、timeMax（RFC3339+tz）、singleEvents（true）、timeZone
GOOGLECALENDAR_CREATE_EVENT	イベントを作成	calendarId、summary、start、end、description、attendees
GOOGLECALENDAR_DELETE_EVENT	イベントを削除	calendarId、eventId

🐙 GitHub

ツールスラッグ	目的	主な引数
GITHUB_CREATE_AN_ISSUE	Issue を作成	owner、repo、title、body、labels、assignees
GITHUB_LIST_REPOSITORY_ISSUES	Issue を一覧表示	owner、repo、sort、state（open/closed/all）、page、per_page
GITHUB_GET_AN_ISSUE	Issue の詳細を取得	owner、repo、issue_number
GITHUB_CREATE_A_PULL_REQUEST	PR を作成	owner、repo、title、head、base、body、draft
GITHUB_LIST_PULL_REQUESTS	PR を一覧表示	owner、repo、state、sort、head、base
GITHUB_MERGE_A_PULL_REQUEST	PR をマージ	owner、repo、pull_number、commit_title、sha
GITHUB_GET_A_REPOSITORY	リポジトリ情報を取得	owner、repo
GITHUB_SEARCH_CODE	コードを検索	q（GitHub 検索構文）、sort、order、per_page
GITHUB_GET_REPOSITORY_CONTENT	ファイル内容を取得	owner、repo、path、ref

# Create issue
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GITHUB_CREATE_AN_ISSUE", "arguments": {"owner": "myorg", "repo": "myrepo", "title": "Bug: login fails", "body": "Steps to reproduce..."}}'

# List open issues
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GITHUB_LIST_REPOSITORY_ISSUES", "arguments": {"owner": "myorg", "repo": "myrepo", "state": "open", "per_page": 10}}'

📝 Notion

ツールスラッグ	目的	主な引数
NOTION_CREATE_NOTION_PAGE	ページを作成	parent_id, title, markdown, icon, cover
NOTION_SEARCH_NOTION_PAGE	ページ/DB を検索	query, filter_value (page/database), page_size
NOTION_QUERY_DATABASE_WITH_FILTER	DB の行をクエリ	database_id, filter, sorts, page_size
NOTION_INSERT_ROW_DATABASE	DB に行を追加	database_id, properties
NOTION_UPDATE_ROW_DATABASE	DB の行を更新	row_id, properties, icon, cover
NOTION_FETCH_DATABASE	DB スキーマを取得	database_id
NOTION_FETCH_BLOCK_CONTENTS	ページの内容を取得	block_id (= page_id)
NOTION_ADD_MULTIPLE_PAGE_CONTENT	ブロックを追加	parent_block_id, content_blocks, after
NOTION_UPDATE_PAGE	ページのプロパティを更新	page_id, properties, icon, cover, archived
NOTION_DELETE_BLOCK	ブロックを削除/アーカイブ	block_id

# Search pages
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "NOTION_SEARCH_NOTION_PAGE", "arguments": {"query": "Meeting Notes", "page_size": 5}}'

# Query database with filter
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "NOTION_QUERY_DATABASE_WITH_FILTER", "arguments": {"database_id": "abc123", "filter": {"property": "Status", "select": {"equals": "In Progress"}}, "page_size": 10}}'

📁 Google Drive

ツールスラッグ	目的	主な引数
GOOGLEDRIVE_CREATE_FILE_FROM_TEXT	ファイルを作成	file_name, text_content, mime_type, parent_id
GOOGLEDRIVE_FIND_FILE	ファイルを検索	q (Drive 検索構文), fields, spaces
GOOGLEDRIVE_DOWNLOAD_FILE	ファイルをダウンロード	fileId, mime_type
GOOGLEDRIVE_COPY_FILE	ファイルをコピー	fileId
GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE	ファイルを共有	fileId, role, type, emailAddress

# Search files by name
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLEDRIVE_FIND_FILE", "arguments": {"q": "name contains '\''report'\'' and mimeType != '\''application/vnd.google-apps.folder'\''"}}'

# Create text file
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLEDRIVE_CREATE_FILE_FROM_TEXT", "arguments": {"file_name": "notes.txt", "text_content": "Hello World"}}'

Google Drive の検索構文 (q パラメータ): name contains 'keyword'、mimeType = 'application/vnd.google-apps.folder' (フォルダー)、'<folderId>' in parents (フォルダー内のファイル)、modifiedTime > '2026-01-01'。

📄 Google Docs

ツールスラッグ	目的	主な引数
GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN	Markdown からドキュメントを作成	title, markdown_text
GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT	ドキュメントをテキストとして取得	document_id, include_tables, include_headers
GOOGLEDOCS_GET_DOCUMENT_BY_ID	生のドキュメントオブジェクトを取得	id

# Create doc with markdown content
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN", "arguments": {"title": "Meeting Notes", "markdown_text": "# Q2 Planning\n\n- Item 1\n- Item 2"}}'

# Read doc as plain text
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLEDOCS_GET_DOCUMENT_PLAINTEXT", "arguments": {"document_id": "1abc...xyz"}}'

📊 Google Sheets

ツールスラッグ	目的	主な引数
GOOGLESHEETS_CREATE_GOOGLE_SHEET1	スプレッドシートを作成	title
GOOGLESHEETS_GET_SHEET_NAMES	スプレッドシート内のシートを一覧表示	spreadsheet_id, exclude_hidden
GOOGLESHEETS_BATCH_GET	セルの値を読み取り	spreadsheet_id, ranges (リスト、A1 形式), majorDimension, valueRenderOption
GOOGLESHEETS_UPDATE_VALUES_BATCH	セルの値を書き込み	spreadsheet_id, data (list of {range, values}), valueInputOption
GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND	行を追加	spreadsheetId, range, values, valueInputOption, insertDataOption
GOOGLESHEETS_SPREADSHEETS_VALUES_BATCH_CLEAR	範囲をクリア	spreadsheet_id, ranges
GOOGLESHEETS_GET_SPREADSHEET_INFO	スプレッドシートの完全なメタデータを取得	spreadsheet_id
GOOGLESHEETS_UPDATE_SHEET_PROPERTIES	シートのプロパティを更新	spreadsheet_id, sheet_id, title, index

# Read cells
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLESHEETS_BATCH_GET", "arguments": {"spreadsheet_id": "1abc...xyz", "ranges": ["Sheet1!A1:D10"]}}'

# Write cells
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLESHEETS_UPDATE_VALUES_BATCH", "arguments": {"spreadsheet_id": "1abc...xyz", "valueInputOption": "USER_ENTERED", "data": [{"range": "Sheet1!A1:B2", "values": [["Name", "Score"], ["Alice", 95]]}]}}'

# Append rows
curl -s -X POST $GATEWAY/internal/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND", "arguments": {"spreadsheetId": "1abc...xyz", "range": "Sheet1!A:B", "valueInputOption": "USER_ENTERED", "values": [["Bob", 88], ["Charlie", 92]]}}'

⚠️ Google Sheets に関する注意:

• valueInputOption: "USER_ENTERED" (数式や数値を解析) または "RAW" (リテラルテキスト)
• ranges は A1 形式を使用します: "Sheet1!A1:D10"、"Sheet1!A:A" (列全体)
• BATCH_GET は data.data.valueRanges[].values (2 次元配列) を返します
• spreadsheetId と spreadsheet_id: ツールによって camelCase を使うものと snake_case を使うものがあります — 不明な場合はスキーマを確認してください

重要な注意事項

• ツールスラッグは大文字です: GMAIL_SEND_EMAIL
• ツールキットスラッグは小文字です: gmail、github
• 引数キー: 常に "arguments" を使用し、決して "params" を使用しないでください — params は黙って無視されます
• 時間パラメータ: タイムゾーンオフセット付きの RFC3339 (2026-04-08T00:00:00+08:00) を使用してください。意図がない限り UTC は使用しないでください
• OAuth トークンは Composio によって管理されています — 有効期限が切れると自動的に更新されます
• レスポンスのネスト: Composio の execute レスポンスは通常 data.data ですが、Twitter は data.data.data (3 階層) です。データに再帰的にアクセスしてパースしてください。
• ネイティブツールへのフォールバック: Composio ツールに制限がある場合 (例: Twitter 検索は 7 日間のみ)、プラットフォーム組み込みのネイティブツール (例: twitter_user_tweets) を優先してください

よくある問題

Browserbase の接続名の不一致

/internal/connections でツールキット browserbase_tool が ACTIVE と表示されているのに、BROWSER_TOOL_* を実行すると「No active connection found for toolkit 'browser'」が返される場合、これはゲートウェイ側のツールキットエイリアスの不一致 (browserbase_tool と browser) です。

対処方法:

1. セッション管理ツール (SESSIONS_*、CONTEXTS_*、UPLOADS_* など) については、ゲートウェイがサーバー側で Browserbase のエイリアスを正規化する必要があります。正規化されない場合は、BROWSER_TOOL_* と BROWSERBASE_TOOL_* の両方のスラッグを試してください。
2. 実際のブラウザ操作 (navigate、click、fill、scrape) については、Composio execute を使用しないでください — 上記の Browserbase セクションで説明されているように Playwright の connect_over_cdp を使用してください。Composio ツールはセッションを管理するだけで、ページ操作は行いません。

Gmail のネストされた JSON のパース

Gmail は複数階層の HTML コンテンツを含む複雑な JSON 構造を返します。json.loads でネストされた文字列をパースしようとしないでください。Python では dict として直接アクセスしてください — ゲートウェイはすでにパース済みの JSON を返します。

---