Stripe Agents Toolkit完全チュートリアル2026

Stripe Agents ToolkitとはどんなSDKか

Stripe Agents Toolkitは、AIエージェントがStripe決済APIを直接操作できるようにするための公式ライブラリだ。2024年末にリリースされ、2026年2月にv0.7.0となった現在、LangChain・OpenAI Agents SDK・CrewAI・Strandsの4フレームワークに対応している。

このSDKの本質は「LLMが関数呼び出し（Function Calling）経由でStripe APIを叩ける」という点にある。エージェントは自然言語の指示を受けて、支払いリンク作成・サブスク管理・請求書発行・顧客情報操作などを自律的に実行できる。

MCP（Model Context Protocol）サーバーとしても動作するため、Claude Desktopや各種AIツールからもStripe操作が可能だ。詳細はStripe公式ドキュメント（Add Stripe to your agentic workflows）を参照。ソースコードはstripe/agent-toolkit（GitHub）で公開されており、v0.7.0（2026年2月リリース）時点でPyPIにstripe-agent-toolkitとして公開されている。

対応フレームワーク一覧

フレームワーク	言語	パッケージ名
LangChain	Python / TypeScript	stripe-agent-toolkit / @stripe/agent-toolkit
OpenAI Agents SDK	Python	stripe-agent-toolkit
CrewAI	Python	stripe-agent-toolkit
Strands	Python	stripe-agent-toolkit
Vercel AI SDK	TypeScript	@stripe/agent-toolkit

インストール方法（Python / npm）

Python環境の場合、pip または uv で導入できる。Python 3.11以上が必要だ。

# pip
pip install stripe-agent-toolkit

# LangGraph と同時インストール
pip install --quiet -U langgraph stripe-agent-toolkit

# uv（推奨）
uv pip install stripe-agent-toolkit

TypeScript / Node.js（Node 18以上）の場合はnpmまたはyarnを使う。

# npm
npm install @stripe/agent-toolkit

# yarn
yarn add @stripe/agent-toolkit

環境変数と初期セットアップ

Stripe APIキーは必ず環境変数で管理する。本番環境では Restricted API Key（rk_〜）を必ず使うこと。シークレットキー（sk_〜）をそのまま使うと全権限を持つキーをエージェントに渡すことになり、セキュリティリスクが大きい。

# .env ファイル
STRIPE_SECRET_KEY=rk_test_xxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxx

import os
from dotenv import load_dotenv

load_dotenv()

STRIPE_KEY = os.getenv("STRIPE_SECRET_KEY")
if not STRIPE_KEY:
    raise ValueError("STRIPE_SECRET_KEY が設定されていません")

テスト環境では rk_test_ または sk_test_ から始まるキーを使う。本番切り替え時は rk_live_ に変更するだけでよい。

LangChain連携（StripeAgentToolkitクラス）

LangChainとの統合は StripeAgentToolkit クラスを使う。configuration の actions で有効にする操作を細かく制御できる点が特徴だ。

import os
from stripe_agent_toolkit.langchain.toolkit import StripeAgentToolkit
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent

# ツールキット初期化 — 使う操作だけ明示的に有効化
stripe_toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "payment_links": {"create": True},
            "customers":     {"create": True, "read": True},
            "subscriptions": {"read": True, "update": True},
            "invoices":      {"create": True, "finalize": True},
            "products":      {"create": True, "read": True},
            "prices":        {"create": True, "read": True},
        }
    },
)

# LLM（Claude 3.5 Sonnetで実行）
llm = ChatAnthropic(model="claude-3-5-sonnet-latest")

# LangGraph ReAct エージェント作成
agent = create_react_agent(llm, stripe_toolkit.get_tools())

# 実行
result = agent.invoke({
    "messages": [("human", "テスト商品「Pro Plan」を月額9,800円で作成し、支払いリンクを発行してください")]
})
print(result["messages"][-1].content)

TypeScript版LangChainの場合は @stripe/agent-toolkit/langchain からインポートする。

import { createStripeAgentToolkit } from "@stripe/agent-toolkit/langchain";
import { ChatOpenAI } from "@langchain/openai";

const toolkit = await createStripeAgentToolkit({
  secretKey: process.env.STRIPE_SECRET_KEY!,
  configuration: {
    actions: {
      payment_links: { create: true },
      customers:     { create: true, read: true },
    },
  },
});

const tools = toolkit.getTools();
const llm = new ChatOpenAI({ model: "gpt-4o" });
// エージェント実行...

OpenAI Agents SDK連携

OpenAI Agents SDKとの統合は stripe_agent_toolkit.openai.toolkit を使う。OpenAI Agents SDKを既に使っているチームにとって最も馴染みやすい選択肢だ。

import os
import asyncio
from agents import Agent, Runner
from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit

async def main():
    # ツールキット作成
    toolkit = await create_stripe_agent_toolkit(
        secret_key=os.getenv("STRIPE_SECRET_KEY"),
    )

    # Stripe操作エージェント定義
    stripe_agent = Agent(
        name="Stripe決済エージェント",
        instructions="""
            あなたはStripe決済の専門エージェントです。
            ユーザーの指示に従い、支払いリンクの作成・顧客管理・
            サブスク管理・請求書発行を正確に実行してください。
            金額の確認なしに課金操作を行ってはいけません。
        """,
        tools=toolkit.get_tools()
    )

    result = await Runner.run(
        stripe_agent,
        input="月額1,980円のBasicプランを新規作成してください"
    )
    print(result.final_output)

asyncio.run(main())

Anthropic Claude SDK連携

Claude SDKと直接組み合わせる場合は、LangChain経由でChatAnthropicを使うのが現時点での標準的なアプローチだ。LangGraphのReActエージェントパターンと組み合わせると、複数ステップの決済フローを自律的に処理できる。

import os
from stripe_agent_toolkit.langchain.toolkit import StripeAgentToolkit
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
from langchain_core.messages import HumanMessage

# Claudeモデル指定
llm = ChatAnthropic(
    model="claude-3-5-sonnet-latest",
    temperature=0,
)

# ツールキット（最小権限）
toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "payment_links": {"create": True},
            "products":      {"create": True},
            "prices":        {"create": True},
        }
    },
)

agent = create_react_agent(llm, toolkit.get_tools())

response = agent.invoke({
    "messages": [HumanMessage(content=
        "AIエージェント研修コース（税込98,000円、買い切り）を作成して"
        "支払いリンクを発行してください"
    )]
})

個別ツール実装例

決済リンク作成（Payment Link）

最もシンプルかつ実用的なユースケースが決済リンクの自動生成だ。チャットボットやサポートbotで「〇〇プランを購入したい」と言われた瞬間にリンクを返せる。

from stripe_agent_toolkit.langchain.toolkit import StripeAgentToolkit

toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "payment_links": {"create": True},
            "products":      {"create": True, "read": True},
            "prices":        {"create": True, "read": True},
        }
    },
)

# エージェントへの指示例
task = """
以下の商品の支払いリンクを作成してください:
- 商品名: Claude Code研修 基礎コース
- 価格: 49,800円（税込）
- 通貨: JPY
- 一回払い
"""

サブスク管理（Subscription）

SaaSサービスのサブスク管理をエージェントで自動化するパターン。プラン変更・解約処理・延滞対応などを自然言語指示で実行できる。

toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "subscriptions": {
                "read":   True,
                "update": True,
            },
            "customers": {
                "read": True,
            },
        }
    },
)

# 使用例
task = "cus_xxxx のサブスクリプション一覧を確認してください"

請求書発行（Invoice）

toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "invoices":      {"create": True, "finalize": True},
            "invoice_items": {"create": True},
            "customers":     {"read": True},
        }
    },
)

# 月次請求書の自動発行フロー
task = """
顧客 cus_xxxx に対して以下の月次請求書を作成・確定してください:
- AIエージェント顧問サービス: 300,000円
- 追加サポート（5時間分）: 100,000円
"""

顧客情報管理（Customer）

toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "customers": {
                "create": True,
                "read":   True,
            },
        }
    },
)

task = """
以下の顧客をStripeに新規登録してください:
- 会社名: 株式会社サンプル
- メール: billing@example.com
"""

Refund処理

toolkit = StripeAgentToolkit(
    secret_key=os.getenv("STRIPE_SECRET_KEY"),
    configuration={
        "actions": {
            "refunds": {"create": True},
        }
    },
)

# 返金処理（必ず人間承認フローを挟む）
task = "payment_intent pi_xxxx に対して全額返金を処理してください"

Webhook処理パターン（Stripe → Agent通知）

Stripeの決済イベントをエージェントに伝えるにはWebhookが必要だ。FastAPIでシンプルなWebhookレシーバーを実装し、イベントに応じてエージェントを起動するパターンを示す。

import os
import stripe
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")
WEBHOOK_SECRET = os.getenv("STRIPE_WEBHOOK_SECRET")

@app.post("/webhook/stripe")
async def stripe_webhook(request: Request):
    payload = await request.body()
    sig_header = request.headers.get("stripe-signature")

    try:
        # 署名検証（必須 — 省略すると偽リクエストを受け入れる）
        event = stripe.Webhook.construct_event(
            payload, sig_header, WEBHOOK_SECRET
        )
    except stripe.error.SignatureVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    event_type = event["type"]

    if event_type == "payment_intent.succeeded":
        payment_intent = event["data"]["object"]
        await activate_service(payment_intent["customer"])

    elif event_type == "invoice.payment_failed":
        invoice = event["data"]["object"]
        await handle_payment_failure(invoice["customer"])

    elif event_type == "customer.subscription.deleted":
        subscription = event["data"]["object"]
        await offboard_customer(subscription["customer"])

    return {"status": "ok"}

エラーハンドリングとRetry戦略

StripeのAPIはネットワーク障害やレート制限で失敗することがある。エージェントの自律動作中にエラーが起きた場合の対処パターンを実装しておく必要がある。

import stripe
import time
from functools import wraps

def stripe_retry(max_retries=3, backoff_base=2):
    """指数バックオフでStripe APIを再試行するデコレータ"""
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except stripe.error.RateLimitError:
                    wait = backoff_base ** attempt
                    print(f"レート制限: {wait}秒後に再試行")
                    time.sleep(wait)
                except stripe.error.APIConnectionError:
                    if attempt == max_retries - 1:
                        raise
                    time.sleep(backoff_base ** attempt)
                except stripe.error.StripeError:
                    raise
            raise Exception("最大再試行回数を超えました")
        return wrapper
    return decorator

@stripe_retry(max_retries=3)
def create_payment_link(price_id: str) -> str:
    link = stripe.PaymentLink.create(
        line_items=[{"price": price_id, "quantity": 1}]
    )
    return link.url

セキュリティ設計（権限スコープとRestricted API Key）

エージェントに渡すAPIキーには最小権限の原則を適用する。Stripeダッシュボードの「Restricted keys」から、操作ごとに権限を絞ったキーを作成できる。

{
  "restricted_key_permissions": {
    "payment_links": "write",
    "products":      "write",
    "prices":        "write",
    "customers":     "read",
    "subscriptions": "read",
    "invoices":      "write",
    "refunds":       "none"
  },
  "note": "refundsはnoneにして人間の承認フローを必須にする"
}

返金（Refund）処理は特に注意が必要だ。エージェントが自律的に返金できる状態は避け、人間の確認ステップを必ずワークフローに組み込む。

テスト環境のセットアップ（test mode / sandbox）

本番への影響なしに開発・デバッグするには、Stripeのテストモードを使う。テストキー（sk_test_ / rk_test_）を環境変数にセットするだけで、全操作がサンドボックス内に閉じる。

import os
import stripe

# テストモードキー
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")  # rk_test_xxxx

# テスト用カード番号（実際の課金は発生しない）
TEST_CARDS = {
    "success":            "4242 4242 4242 4242",
    "declined":           "4000 0000 0000 0002",
    "insufficient_funds": "4000 0000 0000 9995",
    "requires_auth":      "4000 0025 0000 3155",
}

# Stripe CLI インストール（macOS）
brew install stripe/stripe-cli/stripe

# ログイン
stripe login

# ローカルWebhookテスト
stripe listen --forward-to localhost:8000/webhook/stripe

# テスト決済イベント発火
stripe trigger payment_intent.succeeded

実装パターン10選

Stripe Agents Toolkitで実現できる代表的な実装パターンをまとめる。

#	パターン名	概要
1	チャットコマースbot	Slackで「〇〇を購入して」と言うと支払いリンクを返信
2	自動請求書発行	月次でCRM顧客一覧を読んで請求書を一括発行
3	支払い遅延督促エージェント	invoice.payment_failed Webhookを受けてSlack通知
4	SaaSオンボーディング自動化	新規登録 → Customer作成 → サブスク開始 → ウェルカムメール
5	プラン変更提案bot	使用量を見てアップセル提案 → 承認後にSubscriptionアップデート
6	返金審査エージェント	ポリシー判定後に人間承認 → Refund実行
7	売上レポート生成	期間指定でInvoice一覧取得 → CSV / Slack送信
8	マルチテナントSaaS課金	Connected Account経由で加盟店ごとの課金を管理
9	従量課金メーター集計	APIアクセスログをもとにUsage Record送信 → 月末請求
10	AI生成コンテンツのマイクロペイメント	トークン消費量に応じてAgentが自動課金

失敗パターン4選

失敗1: シークレットキー（sk_〜）をそのままエージェントに渡す
全権限を持つキーをLLMに渡すのは危険だ。プロンプトインジェクション攻撃で不正操作されるリスクがある。必ず rk_〜（Restricted Key）を使い、操作を絞ること。

失敗2: Webhookの署名検証を省略する
stripe.Webhook.construct_event() での署名検証を省くと、外部から偽のWebhookを送り込まれてエージェントが誤動作する。絶対に省略しないこと。

失敗3: テストキーと本番キーを混用する
環境変数の管理を怠ると、開発中にテスト意図で書いたコードが本番キーで動いて実際の課金が発生する。.env.test と .env.production を明確に分離すること。

失敗4: エラーハンドリングなしで自律ループを動かす
LangGraphなどで長時間ループを回す場合、APIエラーや不正な入力でエージェントが止まることがある。指数バックオフRetryと最大ループ回数の上限を必ず設定する。

まとめ

Stripe Agents Toolkitは「AIエージェントに決済能力を持たせる」という実装を、最小限のコードで実現できる公式SDKだ。LangChain・OpenAI Agents SDK・Claude経由のいずれでも同じ configuration.actions 構造でツールの権限制御ができる点は設計として洗練されている。

導入時の鉄則は「Restricted API Key + 最小権限」と「Webhookの署名検証」の2点だ。この2つを守れば、チャットコマースbotから自動請求システムまで、安全にAI駆動の決済フローを構築できる。

エージェントフレームワーク選定に迷っている方はAIエージェントFW5強徹底比較も参考にしてほしい。また、OpenAI Agents SDK完全ガイドと組み合わせることで、より複雑なマルチエージェント決済フローも構築できる。