Teardrop

████████╗███████╗ █████╗ ██████╗ ██████╗ ██████╗  ██████╗ ██████╗
╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔══██╗
   ██║   █████╗  ███████║██████╔╝██║  ██║██████╔╝██║   ██║██████╔╝
   ██║   ██╔══╝  ██╔══██║██╔══██╗██║  ██║██╔══██╗██║   ██║██╔═══╝
   ██║   ███████╗██║  ██║██║  ██║██████╔╝██║  ██║╚██████╔╝██║
   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝

Teardrop は、アプリケーションやソフトウェアエージェントがツールを使用する AI ワークフローを実行するためのストリーミング API です。クライアントがメッセージまたはタスクを送信すると、Teardrop は設定済みの LLM（Anthropic、OpenAI、Google、または OpenRouter）と利用可能なツールを調整し、Server-Sent Events（SSE）を介して構造化された結果と UI イベントをストリーミングします。ストリーミングによる対話には AG-UI、エージェントの検出と委任には A2A、ツールへのアクセスには MCP をサポートし、オプションで Base 上の x402 によるリクエストごとの USDC 決済にも対応しています。

---

主な機能

エージェント間（A2A）委任

エージェントは、ゼロコストの discover_agents ツールを使って、オプトインした専門エージェントを検出できます。このツールでは、公開中のアクティブなツール名も確認できます。また、delegate_to_agent を使って安全にタスクを委任できます（どちらも /agent/run の実行中に呼び出されます）。許可リストによる制御、JWT の転送、実行ごとのクォータ、委任先ごとのコスト上限、任意での公開された USDC 建てタスク価格、さらに組織レベルおよび呼び出し元プリンシパル単位の一時停止／24 時間の支出上限の適用に対応した任意のクレジット請求機能を備えています。価格が有効な許可リスト上限を超える場合、資金を確保する前に error_type=advertised_price_exceeds_cap が返されます。上限以下の価格は、最新の予算に照らして再確認されます。クレジットで資金が確保された、新たに紐付けられた委任が確実に未配達となった場合は、返金と紐付いた取消処理が作成され、返金額がローリング支出上限の計算にも復元されます。配達された可能性がある曖昧な呼び出しは、明示的に解決されるまで保留されます。マイグレーション 103 より前に作成された返金行は紐付けられていない場合があり、残高は復元されますが、ローリング上限の余裕は復元されません。

プロトコル仕様、環境変数、許可リスト、請求イベントのペイロードについて詳しくは、docs/a2a-delegation.md を参照してください。

プラットフォームツールマーケットプレイス

Teardrop は、呼び出し元が利用できる組み込みの従量課金ツールを 31 個、マーケットプレイスカタログを通じて公開しています。呼び出し元は、次の方法でこれらのツールを呼び出せます。

• GET /tools/mcp の MCP ゲートウェイ経由（ツールを直接呼び出し、呼び出しごとに課金）。
• エージェント実行中に呼び出されるツールとして（エージェントが使用を決定した場合に POST /agent/run 経由で呼び出し。実行の使用コストに課金）。

ツールの完全な一覧、詳しい説明、呼び出しごとの料金については、docs/tools-catalog.md を参照してください。

MARKETPLACE_ENABLED=true で有効にできます。有効にすると、ツールは GET /marketplace/catalog に qualified_name = "platform/{tool_name}" および tool_type = "platform" として表示されます。カタログでは、category による絞り込み、sort=popularity による並べ替え、個別ツールの詳細ページ、GET /marketplace/authors での作成者一覧、作成者プロフィール、LLM に適した GET /marketplace/llms.txt での検出、GET /marketplace/quote?tool={qualified_name} での現在の有効価格の確認に対応しています。公開カタログには、作成者が公開しているアクティブな項目がすべて掲載されます。認証済みエージェントは、GET /agent/tools で所属組織の現在のインベントリを確認できます。作成者一覧には、アクティブな公開作成者と集計された呼び出し回数が表示され、その後、ツールの詳細を確認できる既存の作成者プロフィールにクライアントが案内されます。これは、リモート A2A 委任 URL の一覧ではありません。集計品質指標は GET /.well-known/reputation.json で利用できます。マーケットプレイスの作成者は、外部 MCP サーバーを登録し、検出したツールを掲載できます（組織管理者、または組織に紐付けられたマシン認証情報が必要です）。登録には POST /marketplace/import/preview と POST /marketplace/import/publish を使用します。 MCP の tools/list には、ツールに呼び出し履歴がある場合、LLM クライアント向けの観測品質の説明と、プログラムで利用するクライアント向けの構造化された _meta["teardrop/reputation"] が含まれます。/tools/mcp のエンドポイントには、プラットフォームツール（名前のみで、x402 またはクレジットで支払い可能）と公開済みの組織ツール（{org_slug}/{tool_name}。Bearer とクレジットのみで利用可能で、Bearer 認証の呼び出し元にのみ一覧表示される）が掲載され、それぞれに _meta["teardrop/price"] が含まれます。旧 /mcp/v1 エンドポイントは非推奨で、2026-10-29 に提供終了します。カタログの cost_usdc は、すべてのエンドポイントで常に請求額と一致します。作成者が価格を設定していないコミュニティツールにはプラットフォームのデフォルト価格が適用され、0 は無料を意味します。メタデータの仕様については、docs/tools-catalog.md を参照してください。

組織は任意で、組織管理者または組織に紐付いたクライアントクレデンシャルトークンを使用して、PUT /marketplace/agent-registration からリモート A2A エンドポイントを 1 つ、公開ディレクトリに登録できます。Teardrop は HTTPS のベース URL のみ受け付け、SSRF チェックを実施してリモートの Agent Card を検出し、A2A クライアントが使用する /message:send エンドポイントを必須とします。レジストリは、外向き呼び出しの許可リストとは別のものです。エンドポイントを公開すると検出可能になりますが、そこへの呼び出しが許可されるわけではありません。GET /marketplace/agents は、オプトインしたエンドポイントを一覧表示します。レピュテーション指標は、異なる呼び出し元の組織が 5 つに達した場合にのみ表示されます。自己トラフィック、ローカルの失敗、および結果が曖昧な possibly_delivered は除外されます。追加された registered_at フィールドは新規参入者の新しさを示す指標にすぎず、品質や所有権を証明するものではありません。このマシンクレデンシャルを使う方法で行えるのは、エンドポイントの登録と MCP ツールの公開です。収益の出金には、組織管理者またはマシンによってプロビジョニングされた組織を所有する SIWE ウォレットが必要です。

エージェント所有の Webhook ツールは、POST /tools から登録できます。マシンによってプロビジョニングされた組織は、所有する SIWE ウォレットを使用して POST /marketplace/author-config からマーケットプレイスの支払いを設定します。組織管理者がトレジャリーウォレットを設定しない限り、ウォレットはその ID に固定されます。作成者の収益記録に支払い設定は不要になりましたが、自己呼び出しは引き続き除外されます。新しいマーケットプレイスツールの公開と出金の申請には、引き続き決済ウォレットの設定が必要です。収益の記録はベストエフォートであり、決済に連動した永続的な保証ではありません。

プラットフォームツールはエージェントの実行中に常に利用可能で、POST /marketplace/subscriptions からサブスクリプションに登録することはできません。また、トークン費用に加えて、マーケットプレイス価格が発生します。組織ごとの価格上書きは POST /admin/pricing/tools から設定できます。エージェントの実行では、同じツールにマーケットプレイスカタログ価格と tool_pricing_overrides の両方がある場合、tool_pricing_overrides が優先されます。

マーケットプレイスのサブスクリプションはエージェント実行時のピンであり、定期支払いプランや MCP への直接アクセス権ではありません。ピンを設定すると、組織の /agent/run ツールセットにコミュニティツールが追加されます。/tools/mcp の直接呼び出しにはピンは不要で、認証と請求の要件はそのまま適用されます。/agent/tools では、従来の access_mode="subscribed" はピン設定済みを意味し、"included" はマーケットプレイスのピンが不要であることを意味します。無料という意味ではありません。ピンやインベントリが実行を保証するものではありません。エージェント実行時のピンとツールの直接呼び出しを参照してください。

マーケットプレイスの決済と USDC のスイープ

組織はマーケットプレイスを通じてエージェントを収益化できます。出金時には、保留中の作成者報酬を確保してから、Coinbase Developer Platform（CDP）経由で設定済みの決済ウォレットに USDC を送金します。確認済みの送金は settled になり、オンチェーンでの取り消しが確認されると報酬が解放されます。送信エラーや確認できない状態のままの送金は in_flight のままとなり、自動返金を防ぐために報酬は保留されます。スイープループは、トランザクションハッシュが記録された in_flight の出金について、トランザクションが確定し、請求済みの USDC 送金と一致した時点で、決済または報酬の解放を行います。その他の判断が曖昧な出金をリセットする前に、運用担当者はチェーン上の結果を確認する必要があります。

自動スイープは MARKETPLACE_AUTO_SWEEP_ENABLED および関連する MARKETPLACE_* 設定で構成します（docs/configuration.md を参照）。管理者 API：POST /admin/marketplace/sweep（手動スイープ）および GET /admin/marketplace/settlement-balance。

メール認証済みユーザー向けオンボーディングクレジット

Teardrop は、新たに認証された組織に少額の前払いクレジット残高を付与できます。これにより、ウォレットやカードをすぐに設定しなくても、最初のエージェント実行が可能になります。この機能はデフォルトで無効（ONBOARDING_CREDIT_ENABLED=false）であり、コンバージョンを促進するためのもので、出金可能なマーケットプレイス収益の原資として利用するものではありません。

ユーザーが単回使用のメール認証トークン（GET /auth/verify-email）を使用すると、クレジットが付与されます。トークンの使用、ユーザーの認証済みステータスへの変更、適格性確認のキュー登録はアトミックにコミットされます。クレジット付与は冪等であり、成功するまでバックグラウンドワーカーが再試行します。プロモーションクレジットは、プラットフォームツール、組織の Webhook ツール、MCP ツール、およびエージェントの基本実行料金に使用できますが、マーケットプレイスの作成者ツールの呼び出しには使用できません。実際のチャージ（Stripe、オンチェーンの USDC、管理者によるチャージ、または返金）が行われると、組織は通常のクレジットステータスに移行し、マーケットプレイスの制限が解除されます。x402 で支払う SIWE 呼び出しには影響しません。

認証後に GET /billing/balance を確認すると、付与された残高を確認できます。ONBOARDING_CREDIT_* 設定については、docs/configuration.md を参照してください。

無人（スケジュール実行）エージェントの実行

組織は、クレジットのみの統合請求、保存された実行履歴、リアルタイムのステータスコールバックを利用して、エージェントの無人実行を定期的にスケジュールできます。/agent/schedules API（POST／GET／PATCH／DELETE、およびカーソルページネーションによる結果取得用の GET /agent/schedules/{id}/runs）で管理します。

実行予定時刻になった実行は、行ロックを行うクエリ（FOR UPDATE SKIP LOCKED）で取得され、実行ごとに障害が分離された状態で並行実行されるため、複数のワーカーインスタンスを水平スケールできます。結果は scheduled_run_results にアーカイブされ、HTTPS 専用かつ SSRF チェック済みのコールバック URL に送信できます。プレーンテキストのモバイル通知には callback_format=text を使用します。デフォルトは JSON です。docs/configuration.md を参照し、SCHEDULED_RUNS_* 設定で構成してください。

スケジュールされた分析プロンプトでは、内部の record_predictions ツールを正確な構造化ペイロードで呼び出し、簡潔な説明レポートのみを返すことができます。Teardrop は、汎用ラベリングデータプレーンを通じて、将来の観測値に対してこれらの予測を非同期にラベル付けします。そのため、コールバックでレポートを下流の通知システムに送信しながら、構造化された値を ML 評価に利用できます。docs/architecture.md および docs/configuration.md の LABELING_* 設定を参照してください。

VOR_ENABLED=true の場合、外部エージェントは POST /labeling/predictions を通じて、ウォレット署名付きの予測をコミットすることもできます。Teardrop は各予測にサーバー側でタイムスタンプを付与し、コミットメントをまとめて Base 上にアンカーされた Merkle ツリーに格納し、GET /labeling/predictions/{id}/proof から包含証明を返します。docs/configuration.md の VOR_* 設定を参照してください。

事前登録済みの公開タスク（現在は oracle_deviation@1。Base 上の Chainlink ETH/USD が Uniswap v3 TWAP からどれだけ乖離したかをスコアリングします）は、固定され、ファイナライズ済みのオンチェーン読み取り値に基づいてスコアリングされます。GET /scorecards/... は認証なしで、カバレッジ調整済みの Brier スコアカードを公開します。予測ペイロードは非公開のままです。

イベントトリガー型（リアクティブ）実行

固定間隔での実行に加えて、組織は受信 Webhook（例：オンチェーンイベント、CRM の更新、CI シグナル）に応じてエージェントを実行するイベントトリガーを登録できます。イベントトリガーにはプロンプトのテンプレートが保存され、ディスパッチ時に受信した JSON ペイロードがテンプレートに挿入されます。イベントトリガーは、スケジュール実行と同じ実行コア、クレジット請求、結果履歴、コールバック配信を使用します。

/agent/event-triggers API（CRUD、シークレットのローテーション、実行状況のポーリング）で管理します。受信イベントのディスパッチには POST /agent/events/{trigger_token} を使用し、トリガーごとのシークレットを X-Teardrop-Trigger-Secret ヘッダーで認証します。オプションの冪等性キーと、インジェクション対策のためのスカラー値限定かつ長さ制限付きのプロンプトへの挿入に対応しています。Postgres の実行リースにより、全体および組織ごとの同時実行数が制限され、上限に達すると 429 が返されます。

next_trigger_id に同じ組織内の別のイベントトリガーを設定すると、コールバック認証を使わずに、完了した実行を内部で連鎖させることができます。チェーンは直線状です。EVENT_CHAIN_MAX_HOPS は子のホップ数を制限します（デフォルト：2。ルートを含めて3 回の実行が可能です。0 にすると子のディスパッチは無効になります）。結果には chain_id と 0 から始まる hop_index が含まれます。子への配信は最大 1 回です。利用できない宛先や上限に達した宛先は監査ログに記録され、再試行されません。

プロンプトテンプレートには信頼できないペイロードデータが挿入されるため、レンダリングされたプロンプトはエージェントに対する信頼できない入力として扱ってください。それに応じて、イベントトリガーで使用するツールとクレジット上限を設定してください。docs/configuration.md を参照し、EVENT_TRIGGERS_* および EVENT_CHAIN_MAX_HOPS 設定で構成してください。

X（Twitter）へのブロードキャスト投稿

組織は、スケジュール実行を設定して、市場分析や機会に関する判定を X（Twitter）に直接ブロードキャストできます。callback_format=x を設定すると、実行が正常に完了した際に、v2 API と OAuth 1.0a 認証を使用して最終出力テキストを X に公開し、公開されたツイート ID を変更不可の x_broadcasts 監査台帳に記録します。

ブロードキャスト実行には、X_BROADCAST_ENABLED=true と、X_BROADCAST_ORG_ID で指定されたオペレーター組織が必要です。それ以外の組織によるスケジュールは 403 で拒否されます。従量課金 API コストの増加やフィッシングを防ぐため、URL を含む出力テキストは公開前に拒否されます。X_* 設定で構成してください（docs/configuration.md を参照）。

---

要件

• Python 3.12+
• 選択した LLM プロバイダーの API キー：Anthropic、OpenAI、または Google AI（BYOK またはセルフホスト可能な環境を使用する場合は任意）
• Postgres データベース（Docker 経由でローカルに実行するか、本番環境では Neon を使用）
• Redis（キャッシュ用、任意。使用しない場合は TTL 付きのインメモリキャッシュにフォールバックします）

---

セットアップ（PowerShell）

1. プロジェクトをクローンしてディレクトリに移動する

git clone https://github.com/teardrop-ai/teardrop.git
cd teardrop

2. 仮想環境を作成して有効化する

python -m venv venv
.\venv\Scripts\Activate.ps1

スクリプト実行エラーが発生した場合は、まず次を実行してください。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. 依存関係をインストールする

pip install -r requirements.txt

4. 環境を設定する

Copy-Item .env.example .env

必要最小限の内容：

# Global LLM provider fallback: anthropic | openai | google | openrouter (default: openrouter)
# Note: Each org can override via PUT /llm-config
AGENT_PROVIDER=openrouter
# Default model is ~deepseek/deepseek-flash-latest.
# For OpenRouter DeepSeek models, Teardrop delegates provider eligibility to the API key's OpenRouter data policy.
OPENROUTER_API_KEY=sk-or-...      # required if AGENT_PROVIDER=openrouter
# ANTHROPIC_API_KEY=sk-ant-...     # required if AGENT_PROVIDER=anthropic
# OPENAI_API_KEY=sk-...           # required if AGENT_PROVIDER=openai
# GOOGLE_API_KEY=...              # required if AGENT_PROVIDER=google

DATABASE_URL=postgresql://teardrop:teardrop@localhost:5432/teardrop

# Optional: Redis for distributed caching
# REDIS_URL=redis://localhost:6379/0

5. RSA キーを生成する

RSA キーペアはアプリの起動時に自動生成されます（keys/ 内）。 手動で事前に生成する場合（任意）は、次を実行してください。

python scripts/generate_keys.py

6. データベースのマイグレーションを実行する

python -m migrations.runner

7. デフォルトの組織と管理者ユーザーをシードする

python scripts/seed_users.py

8. API サーバーを起動する

uvicorn teardrop.main:app --reload

サーバーは http://localhost:8000 で起動します。インタラクティブな API エクスプローラーは http://localhost:8000/docs にアクセスしてください。

---

デプロイ

Docker（ローカルのフルスタック）

docker compose build --pull
docker compose up

Postgres と Teardrop API が起動します。起動時にマイグレーションが自動実行されます。キーはビルド時に生成され、./keys/ からマウントされます。再ビルドの前に docker compose build --pull を実行して、更新されたベースイメージを取得してください。完全に新しい状態で再ビルドする場合は --no-cache を追加してください。

Render（本番環境）

このリポジトリには render.yaml が含まれており、Neon Postgres と共有 Redis サービスに接続する、Standard（1c-2g）の Web サービスインスタンス 1 台を設定します。デフォルトのデータベース接続予算は 7 で、各インスタンスにつきアプリケーションプール接続が最大 6 つ、LangGraph チェックポインター接続が 1 つです。デプロイまたはインスタンス数を増やす前に、設定済みの Neon 接続上限に対して十分な余裕があることを確認してください。

環境変数、セキュリティ認証情報、データベース設定、レート制限の上限の包括的な一覧については、専用のリファレンスガイド docs/configuration.md を参照してください。

---

認証

Teardrop は RS256 JWT を発行します。保護されたビジネスエンドポイントには Bearer トークンが必要です。以下で説明する公開認証、登録、課金価格、ヘルスチェック、ドキュメント、エージェントカード、および決済が必要な POST /message:send A2A サーフェスは、認証なしで引き続き利用できます。

1. クライアント認証情報（マシン間）

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<JWT_CLIENT_SECRET>"}'
$token = $resp.access_token

生成される JWT には auth_method: "client_credentials" が含まれます。.env に JWT_CLIENT_ID と JWT_CLIENT_SECRET を設定してください。

2. メールアドレスとパスワード

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"email":"[email protected]","secret":"<password>"}'

生成される JWT には auth_method: "email" が含まれます。POST /admin/users でユーザーを作成してください。

3. SIWE — Ethereum によるサインイン

SIWE を使うと、Ethereum ウォレットの所有者はパスワードなしで認証できます。発行される JWT には auth_method: "siwe" と呼び出し元の address が含まれます。

1. GET  /auth/siwe/nonce   → { "nonce": "abc123..." }
2. Construct an EIP-4361 SIWE message with that nonce
3. Sign with your wallet (EIP-191)
4. POST /token  { "siwe_message": "...", "siwe_signature": "0x..." }
   → { "access_token": "..." }

SIWE トークンはウォレットの本人確認に使用され、新しいウォレットアドレスは初回ログイン時に自動登録されます。マシンによってプロビジョニングされた SIWE 組織は、エージェント実行にプリペイドクレジットを使用します。このクレジットは、以下のエージェント資金調達ループを通じて補充してください。

4. x402 による支払い優先のブートストラップ

外部エージェントは、メールアドレス、人間によるサインアップ、事前の JWT がなくてもアカウントをブートストラップできます。/.well-known/agent-card.json または /.well-known/x402 の bootstrap ブロック（/.well-known/x402.json も利用可能）からフローを確認し、{"grant_type":"x402"} を指定して POST /token を送信します。ブートストラップの検出には、BILLING_ENABLED、MACHINE_PROVISIONING_ENABLED、X402_ONBOARDING_ENABLED が必要です。支払い要件は、トップレベルの実行価格である accepts とは別です。検出時の価格は参考情報です。最初のトークン応答には 402 Payment Required が含まれ、クライアント認証情報による実行予約額を満たすのに十分なプリペイドクレジットを得るための、現在の x402 要件が示されます。署名済みの Payment-Signature ヘッダー（または旧形式の X-Payment ヘッダー）を付けて再試行します。

最初の決済が正常に完了すると、Teardrop は有効期間の短いアクセストークンと、一度だけ発行される client_id および client_secret を返します。シークレットはすぐに保存してください。後から取得することはできません。その認証情報を使い、以降の課金対象の実行には既存のクライアント認証情報による /token フローを使用します。マシンプロビジョニングされた組織にはプロモーションクレジットは付与されず、設定済みの MACHINE_ORG_DAILY_SPEND_LIMIT_USDC のローリング上限（デフォルト：24 時間あたり $5.00）で開始します。信頼済み組織に明示的に設定された運用者指定の組織上限は維持されます。保存された上限がゼロの場合は、設定済みのデフォルト値が適用されます。

エージェントの資金補充ループ

一度ブートストラップしたら、返されたクライアント認証情報を使って GET /billing/topup/usdc/requirements?amount_usdc=... を呼び出し、返された x402 要件に署名します。プリペイド残高が尽きる前に、署名済みヘッダーを POST /billing/topup/usdc に送信します。既存のマシン組織に対しても、grant_type=x402 による再度の支払いが受け付けられます。この場合、既存のクライアント ID が再利用され、client_secret は省略されます。元のシークレットを紛失した場合は、SIWE で認証し、POST /org/credentials/regenerate を使用します。

トークンの有効期限とリフレッシュトークン

メール、クライアント認証情報、SIWE の認証方法では、有効期限が 30 分 のアクセストークンが発行されます（トークン応答の expires_in: 1800 秒）。x402 のブートストラップでも有効期間 30 分のアクセストークンが返されますが、リフレッシュトークンは発行されません。30 分を超えるセッションが必要なアプリケーションでは、メールまたは SIWE フローのリフレッシュトークンを使用してください。

• リフレッシュトークンの有効期限は 30 日 です。新しいアクセストークンとローテーション済みのリフレッシュトークンに交換できます。
• リフレッシュトークンのローテーションは、冪等性のあるリプレイ保護とアトミックに実行されます。リプレイ期間内に同じリフレッシュトークンが 2 回送信された場合、重複を作成せず、同じ新しいトークンのペアが返されます。
• POST /auth/logout による単一ログアウトでは、リフレッシュトークンが無効化され、セッションが直ちに終了します。

# 1. Exchange refresh token for new access token + rotated refresh token
$resp = Invoke-RestMethod -Uri "http://localhost:8000/auth/refresh" `
    -Method Post -ContentType "application/json" `
    -Headers @{ "Cookie" = "refresh_token=<your-refresh-token>" }
    # OR pass as body: -Body '{"refresh_token":"<your-refresh-token>"}'

# New access token and rotated refresh token are in the response
$newAccessToken = $resp.access_token
$newRefreshToken = $resp.refresh_token  # Use this on your next refresh

# 2. Logout (revoke refresh token)
Invoke-RestMethod -Uri "http://localhost:8000/auth/logout" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $accessToken" }

---

LLM の設定（組織ごと）

組織は、希望する LLM プロバイダー、モデル、ルーティング戦略を設定でき、必要に応じて独自の API キー（BYOK）を使用できます。これにより、次のことが可能になります。

• 複数プロバイダーからの選択：Anthropic、OpenAI、Google を使用するか、セルフホストのエンドポイント（vLLM、Ollama、OpenRouter）を指定できます。
• 独自のキーの持ち込み（BYOK）：独自の API 認証情報を暗号化して保存できます。Teardrop がキーを参照することはありません。BYOK を使用する組織は、プラットフォームのオーケストレーション料金のみを支払います（BYOK_TIER_PRICING_ENABLED=true の場合はトークンごとの料金、それ以外の場合は定額料金）。LLM プロバイダーへの料金は、組織が独自のキーを使って直接支払います。
• スマートルーティング：コスト、速度、品質に基づいてモデルを自動選択します。
• セルフホストへの対応：api_base パラメーターを使って、OpenAI 互換の任意のエンドポイントを使用できます。

組織の LLM 設定エンドポイント

Method	Path	Auth	Description
GET	/llm-config	Bearer	組織の LLM 設定を取得します（未設定の場合はグローバルのデフォルト設定を取得します）
PUT	/llm-config	Bearer	組織の LLM 設定を設定または更新します
DELETE	/llm-config	Bearer	設定を削除し、グローバルのデフォルト設定に戻します

例：コストベースのルーティングを使用して、組織の LLM を GPT-4o に設定する

$token = (Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<secret>"}').access_token

Invoke-RestMethod -Uri "http://localhost:8000/llm-config" `
    -Method Put -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Body @{
        provider = "openai"
        model = "gpt-4o"
        routing_preference = "cost"  # or "speed", "quality", "default"
        max_tokens = 4096
        temperature = 0.7
    } | ConvertTo-Json

BYOK の場合は、独自の api_key を追加します（保存時に暗号化されます）。セルフホストのエンドポイント（vLLM、Ollama、または OpenAI 互換サーバー）の場合は、api_base にエンドポイント URL を設定します。

推論のヒントはプロバイダーによって異なります。Google では、モデルごとにドキュメント化された思考レベルまたは予算が使用されます（Gemini 3.8 Flash では none は low になります）。認識されない Google モデル ID では、プロバイダーのデフォルトが維持されます。OpenRouter には reasoning.effort が渡されますが、使用できる値はモデルの対応状況によって異なります。OpenAI と Anthropic のネイティブ BYOK では、デフォルトが維持されます。優先順位と制限については、推論の労力の互換性を参照してください。

ルーティング設定

routing_preference に "default" 以外の値を設定すると、Teardrop は基準に基づいて標準プールからモデルを自動的に選択します。

設定	動作
default	設定したプロバイダー／モデルを使用します
cost	最も安価なモデルを選択します（入力トークンと出力トークンの料金に基づきます）
speed	最速のモデルを選択します（稼働中のベンチマークによる p95 レイテンシに基づきます。新しいデプロイでは公式仕様にフォールバックします）
quality	品質が最も高いモデルを選択します

注：BYOK（カスタム API キー）を設定すると、ルーティングは無効になり、常に設定したモデルが使用されます。

LLM クレジットモデル

Teardrop の前払いクレジット（またはオンチェーンの x402 決済）で、実行ごとの全費用をまかないます。ただし、明細は組織がプラットフォームの LLM キーを使用するか、BYOK を使用するかによって異なります。

モード	LLM プロバイダーへの支払い元	Teardrop が組織から差し引く料金
プラットフォームキー（デフォルト）	Teardrop	実行モデルの pricing_rules 行に基づくモデルのトークン料金と、ツール呼び出し料金
BYOK	組織が独自のキーを通じて直接支払います	プラットフォームのオーケストレーション料金（定額の BYOK_PLATFORM_FEE_USDC。デフォルトは 1 実行あたり $0.001。BYOK_TIER_PRICING_ENABLED=true の場合はトークン単位のオーケストレーション料金が適用され、定額料金が下限となります）と、ツール呼び出し料金。この料金は、使用イベントおよび SSE の請求イベントで platform_fee_usdc として表示されます。

ツール呼び出し料金は、すべてのサーフェスとすべてのモデルで同じ方法で決まります。管理者による上書き、次に作成者またはプラットフォームの料金、最後にグローバルな pricing_rules.tool_call_cost が適用されます。モデル固有のルールで料金が設定されるのはトークンのみです。単位ごとの料金が設定されていないルールは定額料金となります。その run_price_usdc は 1 回の実行につき 1 回（LLM のターンごとではなく）トークン料金をまかない、ツール呼び出し料金は別途請求されます。

エージェントの実行では、ツール呼び出しが成功した場合、またはツールが報告するビジネスエラー（たとえば、未知のプロトコルやウォレット）が返された場合に料金が発生します。タイムアウト、上流の停止やレート制限、無効な上流応答、無効な引数、予期しないエグゼキューターエラーなど、インフラストラクチャの障害には料金が発生しません。

つまり、BYOK を使用しても、Teardrop のクレジットや x402 決済が不要になるわけではありません。Teardrop の請求から LLM モデル料金が除外されるだけです。

---

モデルのベンチマーク

Teardrop は、デプロイされているすべての LLM の運用指標を継続的に追跡します。これらのベンチマークは、モデルのルーティング判断に活用されます。

ベンチマークのエンドポイント

メソッド	パス	認証	説明
GET	/models/benchmarks	—	公開：カタログのメタデータと稼働中の指標を含むすべてのモデル
GET	/models/benchmarks/org	Bearer	組織スコープ：自組織の使用状況に関する指標のみ

メトリクスについて

各モデルのエントリーには、カタログのメタデータ（provider、model、display_name、context_window、supports_tools、quality_tier、pricing）に加えて、ライブのbenchmarksが含まれます。

• total_runs_7d：過去7日間にこのモデルを使用した実行回数（ベンチマークは実行回数が10回以上の場合のみ含まれます）
• avg_latency_ms：開始から完了までの平均時間（ミリ秒）
• p95_latency_ms：レイテンシの95パーセンタイル（実行のうち遅い方の5％）
• avg_cost_usdc_per_run：実行1回あたりの平均コスト（入力＋出力トークン＋ツール）
• avg_tokens_per_sec：ストリーミングのスループット（リアルタイムアプリケーションに有用）
• quality_tier：品質に基づくルーティングに使用する固定ティア（1＝最良、2＝良好）

---

請求と支払い（x402）

Teardrop は x402 payment protocol を実装しています。BILLING_ENABLED=trueの場合、リクエストには支払いが必要です。開発中に請求なしで実行するには、BILLING_ENABLED=false（デフォルト）に設定してください。

仕組み

Teardrop は x402 payment protocol を実装しています。BILLING_ENABLED=trueの場合、リクエストには支払いが必要です。開発中に請求なしで実行するには、BILLING_ENABLED=false（デフォルト）に設定してください。

未払いのPOST /agent/runは、x402 v2 のPaymentRequiredエンベロープ（PAYMENT-REQUIREDヘッダーと、レガシーのX-PAYMENT-REQUIREDヘッダー）を含む402 Payment Requiredを返します。クライアントは支払いに署名して、Payment-Signatureヘッダーを付けて再試行します。Teardrop はファシリテーターを使用して署名を検証し、SSE レスポンスをストリーミングして、実行後にオンチェーンのtx_hashを含むBILLING_SETTLEMENTイベントを送信します。

認証タイプ別の支払い方法

認証方法	支払い方式
siwe	人が所有する組織：x402 によるオンチェーン決済（USDC、exactまたはupto方式、リクエストごと）；マシンによってプロビジョニングされた組織：前払いクレジットのみ（厳格な1日あたりの上限が適用されます）
client_credentials	組織の前払いクレジット残高（オフチェーンでの引き落とし）
email	組織の前払いクレジット残高（オフチェーンでの引き落とし）

x402 による支払いを先に行うブートストラップでは、予備額相当の x402 支払いを請求し、認証情報の発行前に決済します。その後、新しい組織に、対応する原子的な USDC 額をクレジットとして付与します。確認済みメールアドレス向けのプロモーションクレジットは使用しません。認証済みのマシン認証情報では、実行ごとの支払いの代わりに、より大きな金額をより低い頻度で補充する/billing/topup/usdc残高補充経路を利用できます。

x402 の支払い方式

方式	仕組み	設定
exact（デフォルト）	クライアントが実行の正確な価格に署名し、ファシリテーターがその金額を決済します。	X402_SCHEME=exact
upto	クライアントが上限額（X402_UPTO_MAX_AMOUNT）に署名します。実行後、Teardrop は Permit2 を通じて実際の使用コスト（上限以下）を決済します。	X402_SCHEME=upto

upto クライアントの要件：X402_SCHEME=uptoを使用する前に、支払いに使用するウォレットで、対象チェーン上の USDC に対する Permit2 の承認を一度行う必要があります。 IERC20(USDC).approve(PERMIT2_ADDRESS, type(uint256).max)。これはウォレットごとに一度だけ行うオンチェーントランザクションです。Permit2 を承認していないクライアントは、402レスポンスのaccepts配列にあるscheme: exactを常に代替手段として使用できます。

価格設定

価格はpricing_rulesデータベーステーブルを通じて動的に設定されます。現在の料金（使用量ベース v1）：

メトリクス	料金
入力トークン	$0.0015 / 1k トークン
出力トークン	$0.0075 / 1k トークン
ツール呼び出し	デフォルトで$0.001 / 回；プラットフォームツールにはツールごとの価格が適用されます（最低$0.005、docs/tools-catalog.mdを参照）
実行あたりの最低料金	$0.01

現在の価格を確認：GET /billing/pricing

x402 クライアントとして実行する（SIWE 支払い）

# 1. Get a SIWE JWT (see Authentication above)
# 2. Call /agent/run — you'll get a 402 with payment requirements
# 3. Construct and sign the x402 transferWithAuthorization (EIP-3009)
# 4. Retry with the signed payment header

Invoke-RestMethod -Uri "http://localhost:8000/agent/run" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token"; "Payment-Signature" = "<x402-header>" } `
    -Body '{"message":"What is the ETH balance of vitalik.eth?","thread_id":"session-1"}'

実行の完了後、ストリームにはオンチェーンのtx_hashを含むBILLING_SETTLEMENTイベントが含まれます。

クレジットの補充（マシンからの呼び出し）

管理者は、組織の残高に前払い USDC クレジットを追加できます。

Invoke-RestMethod -Uri "http://localhost:8000/admin/credits/topup" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $adminToken" } `
    -Body '{"org_id":"org-123","amount_usdc":1000000}'   # $1.00

請求関連の環境変数（BILLING_ENABLED、X402_*、BILLABLE_AUTH_METHODSなど）の一覧については、docs/configuration.mdを参照してください。

---

A2A 委任とエージェント間の収益ルーティング

Teardrop エージェントは、タスクをリモートの A2A 準拠エージェントに委任し、その委任費用を呼び出し元の組織に請求できます。これにより、分散型の専門化、組み込みの支出オーケストレーション、自動的な収益ルーティングが可能になります。

機械可読な /.well-known/registry-benefits.json コントラクトでは、組織が A2A エンドポイントを登録する方法、受けられるディスカバリーおよび参考情報としての評判上のメリット、そして意図的に提供対象外としている保証について説明しています。

プロトコルの詳細な仕様、システム構成、許可リスト、課金イベントのペイロード構造については、docs/a2a-delegation.md ガイドをご覧ください。

---

Agentic Market への公開

有料 A2A サーフェスの完全な公開 URL（例：https://api.teardrop.dev/message:send）を POST メソッドとともに使用してください。オリジンのみの https://api.teardrop.dev/ は登録しないでください（GET / は /docs にリダイレクトされ、POST / は有料エントリーポイントではありません）。

Agentic Market のバリデーターは、/.well-known/x402、/.well-known/x402.json、および設定されたエンドポイント URL をプローブする場合があります。Teardrop はこれらのディスカバリー用エイリアスを公開し、未払いの匿名 POST /message:send リクエストに対して、本文を検証する前に x402 チャレンジを発行します。このチャレンジには、完全な x402 v2 PaymentRequired エンベロープ（PAYMENT-REQUIRED）、旧式の X-PAYMENT-REQUIRED エイリアス、有料サーフェスを説明するトップレベルの resource（url、説明、および Teardrop 共通の serviceName、tags、iconUrl）、さらに A2A のリクエスト／レスポンス形式を示す extensions.bazaar が含まれます。

MCP エンドポイント POST https://api.teardrop.dev/tools/mcp も、バリデーターに対して同じように動作します。匿名の POST で本文が空、または JSON-RPC メッセージではない場合、あるいは Accept ヘッダーに text/event-stream が含まれない匿名の GET の場合、HTTP 402 が返されます。このレスポンスの extensions.bazaar は、有料の tools/call の例（get_token_price）を宣言し、そのツールの料金を示します。未払いの匿名 tools/call リクエストには、ツールごとの MCP Bazaar メタデータが返されます。完全なスキーマが 402 ヘッダーの上限を超える場合、ツールの出力スキーマにはトップレベルのフィールドのみが含まれます。すべての MCP 402 の resource にも Bazaar サービスメタデータ（serviceName、tags、および AGENT_CARD_ICON_URL が絶対 http(s) URL の場合はその値を使う iconUrl）が含まれるため、カタログでリスティングに名前を付けられます。SSE の GET、認証済みリクエスト、MCP ハンドシェイク、tools/list は通常の MCP トランスポートを使用します。

Bazaar では、CDP ファシリテーターを通じてそのツールへの支払いが決済された後に限り、各 MCP ツールが個別に一覧表示されます。python -m scripts.seed_bazaar_listings --base-url https://api.teardrop.dev は、支払いを行わずにすべての有料ツールの料金を見積もります。TEARDROP_SEED_PRIVATE_KEY を設定して --execute を追加すると、ツールごとに決済済みの呼び出しを 1 回行います。最初の失敗時点で停止し、ゲートウェイの 402 に Bazaar メタデータまたは出力宣言がない場合は支払いを行いません。CDP ファシリテーターは MCP タイプのレコードから serviceName、tags、iconUrl を削除するため、Teardrop のブランドが Agentic.Market などのカタログに表示されるのは、同じメタデータを含む HTTP /message:send のリスティングを通じてのみです。--a2a --execute を付けて一度シードしてください。

Smithery への公開

Teardrop は、/.well-known/mcp/server-card.json を通じて MCP ツールを自動的に公開します。Smithery で配布するには、次の手順に従ってください。

1. Teardrop インスタンスの公開ベース URL を Smithery の URL Deployment ウィザードにコピーします。
2. x402 の匿名機能を公開するため、Smithery CLI または公開ウィザードで、次の Configuration Schema (JSON) を指定します。

   {
     "type": "object",
     "properties": {
       "apiKey": {
         "type": "string",
         "title": "API Key",
         "x-from": { "header": "x-teardrop-key" },
         "x-to": { "header": "Authorization" }
       }
     }
   }
   

3. Smithery ダッシュボードで Display Name、Description、Homepage、Icon を設定し、品質スコアを最大の 100/100 にします。

MCP レジストリへの公開

公式リスティングは、https://api.teardrop.dev/tools/mcp（Streamable HTTP、パッケージなし）の io.github.HASAVAGE/teardrop です。メタデータはリポジトリのルートにある server.json に保存されており、name は公開済みの名前空間と一致している必要があります。新しいバージョンを公開するには、server.json の version と remotes を更新してから、リポジトリのルートで mcp-publisher validate、mcp-publisher login github、mcp-publisher publish を実行します。

API リファレンス

Teardrop では、OpenAPI を使用したインタラクティブなビジュアル API エクスプローラーを /docs（Swagger UI）と /redoc（ReDoc UI）で提供しています。

Core、Auth、Billing、Marketplace、Wallets、Admin、Custom Tools、Memory、MCP Federation、A2A Delegation の各領域にわたるすべてのエンドポイントを網羅した一覧表については、docs/api-reference.md ガイドを参照してください。

---

MCP ツールサーバーの実行（任意）

Claude Desktop、VS Code、または MCP 互換クライアントで使用するために、MCP プロトコル経由でツールをスタンドアロンで提供できます。

# stdio transport (default – for Claude Desktop / VS Code)
python tools/mcp_server.py

# HTTP SSE transport
python tools/mcp_server.py --transport=sse

---

仕組み

Teardrop は、LangGraph のルーティング／チェックポイントアダプターの背後でポータブルなエージェントノードを使用し、フレームワークに依存しないランタイムイベントを Server-Sent Events（SSE）レイヤーに出力します。

アーキテクチャ設計の全容、実行フローの状態図、SSE ストリームイベントの説明、構造化された A2UI コンポーネントスキーマについては、docs/architecture.md のリファレンスを参照してください。

---

データベース

Teardrop は Postgres を使用します（本番環境には Neon を推奨、開発環境では Docker 経由でローカルに使用します）。

マイグレーション

有効なスキーマ変更は migrations/versions/ にあります。現在の 102_squashed_baseline.sql は、migrations/archive/ にある過去のファイルを置き換えます。次のコマンドでマイグレーションを実行します。

python -m migrations.runner

有効なベースライン、置き換えマニフェスト、スキーママイグレーション、シードエントリ、インデックスの過去のカタログについては、docs/migrations.md を参照してください。

Neon（本番環境）

DATABASE_URL に Neon の接続文字列を設定します。postgresql:// 形式を推奨します。従来の postgresql+asyncpg:// 形式も引き続き使用できます。

---

プロジェクト構成

teardrop/
  app.py              # FastAPI app, lifespan, middleware, background workers, router registration
  main.py             # Compatibility entrypoint (re-exports teardrop.app)
  routers/            # APIRouter modules (agent.py, billing.py, marketplace.py, auth.py, admin/, org/, …)
  config.py           # Settings via pydantic-settings (reads .env)
  auth.py             # RS256 JWT & refresh tokens (email, client_credentials, SIWE)
  users/              # Org + User models, CRUD, PBKDF2-SHA256 password hashing
  billing/            # x402 billing layer, pricing, invoice queries, credit system
  marketplace/        # Marketplace catalog, earnings, reputation, subscriptions, withdrawals
  mcp_client/         # Per-org MCP client: CRUD, session pool, tool discovery
  org_tools/          # Per-org custom webhook tools: CRUD, caching, execution
  memory.py           # Per-org pgvector memory: LLM extraction, recall, CRUD
  agent/              # LangGraph graph, nodes, LLM factory, runtime context/events
  agent_runtime.py    # Agent run orchestration (scheduled/event-triggered runs)
  mcp_gateway.py      # MCP gateway middleware (direct tool invocation + billing)
tools/
  registry.py         # ToolRegistry: versioned, with deprecation lifecycle
  mcp_server.py       # Standalone MCPServer for MCP protocol clients
  definitions/        # One file per tool (calculate, get_datetime, web_search, …)
migrations/
  runner.py           # Applies active SQL migrations and squash baselines
  versions/           # Active SQL and .replaces manifests
  archive/            # Git-only historical migrations superseded by baselines
shared/               # Internal shared utilities: db pool registry, audit inserts, webhook caller
scripts/              # generate_keys.py, seed_users.py, audit_dependencies.py, export_api_spec.py, …

アーキテクチャ設計の全容、実行フローの状態図、SSE ストリームイベントの説明、構造化された A2UI コンポーネントスキーマについては、docs/architecture.md のリファレンスを参照してください。

---

Coinbase Developer Platform との統合

Teardrop は、Coinbase Developer Platform（CDP）を介して組織ごとに USDC ウォレットをプロビジョニングし、委任の支払いとマーケットプレイスの収益を受け取れるようにします。この機能には、CDP アカウント（cdp.coinbase.com）と wallet:create 権限を持つ API キー（Key ID、Key Secret、Wallet Secret）が必要です。AGENT_WALLET_* および CDP_* 環境変数で設定してください（docs/configuration.md を参照）。CDP の料金は操作あたり $0.005 です。無料枠には月あたり 5,000 回の操作が含まれます。

各組織は、チェーンごとに 1 つのウォレットを保有できます（例：Base Sepolia テストネット、Base メインネット）。ウォレットは委任の支払いと MCP マーケットプレイスの収益を自動的に受け取ります。

---

ライセンス

Teardrop は Business Source License 1.1 の下でライセンスされています。

• 本番環境以外での評価および開発には、無料で使用できます。
• 商用の本番環境での使用には、メンテナーからの商用ライセンスが必要です。
• 変更日： 2030 年 4 月 3 日 — この日、コードは自動的に AGPL-3.0-only に切り替わります。

詳細な条件については LICENSE を参照してください。商用ライセンスに関するお問い合わせは、 LICENSE ファイルに記載されている連絡先をご確認ください。

同じライセンスの下で貢献を歓迎します。CONTRIBUTING.md を参照してください。 セキュリティ上の脆弱性を報告するには、SECURITY.md を参照してください。