Stripe Agent Toolkit

Common errors

• stripe.error.AuthenticationError: No API key provided.

  cause The Stripe secret key was not provided during the toolkit initialization or was an empty string.
  fix Ensure the `secret_key` parameter is correctly passed to `create_stripe_agent_toolkit` or `StripeAgentToolkit`, typically by loading it from an environment variable (e.g., `os.environ.get('STRIPE_SECRET_KEY')`).

• stripe.error.PermissionError: Your API key does not have permissions to access this resource.

  cause The Restricted API Key (rk_*) used to initialize the toolkit does not have the necessary permissions for the Stripe API action the agent attempted to perform.
  fix Review the permissions configured for your Restricted API Key in the Stripe Dashboard. Add the specific read/write permissions required for the Stripe API resources (e.g., `payment_links`, `products`) that your agent needs to interact with.

• AttributeError: 'StripeAgentToolkit' object has no attribute 'some_missing_api_call'

  cause The agent attempted to call a Stripe API function that is not exposed or supported by the `stripe-agent-toolkit`.
  fix Verify that the desired Stripe API functionality is part of the supported subset offered by the `stripe-agent-toolkit`. If it's not, you may need to use the native `stripe` Python SDK directly for that specific call or rethink the agent's approach.

• ModuleNotFoundError: No module named 'stripe_agent_toolkit.openai'

  cause Attempting to import from `stripe_agent_toolkit.openai.toolkit` (or similar submodules for other frameworks) without having the corresponding optional dependencies installed.
  fix Install the necessary optional dependencies using `pip install stripe-agent-toolkit[openai]` (or `[langchain]`, `[crewai]`, etc.) to ensure the submodule is available.

Warnings

• gotcha Always use Restricted API Keys (rk_*) in production for enhanced security and to limit the agent's access to only the necessary Stripe API functionality. Standard secret keys (sk_*) grant broad access.
  Fix: Create a Restricted API Key in your Stripe Dashboard (dashboard.stripe.com/apikeys) and assign only the minimum required permissions for your agent's tasks. Use this rk_ key instead of a full sk_ key.
• gotcha The Stripe Agent Toolkit does not expose the entire Stripe API. It provides a curated subset of functionalities relevant to agentic workflows. Attempting to access unsupported Stripe API features through the toolkit will result in errors.
  Fix: Consult the official `stripe-agent-toolkit` documentation and examples to understand the supported Stripe API actions. If a required API is missing, consider contributing or using the raw Stripe Python SDK for that specific functionality outside the agent toolkit context.
• gotcha Agent behavior can be non-deterministic. When integrating the toolkit with AI agents that perform financial transactions, unexpected outcomes can occur if not properly managed.
  Fix: Thoroughly test your agent in a sandbox environment (using Stripe's test mode keys) and implement robust error handling, monitoring, and human oversight mechanisms. Define clear boundaries for agent actions and consider explicit user confirmation steps for critical financial operations.
• deprecated Direct instantiation of `StripeAgentToolkit` via `StripeAgentToolkit(...)` might be replaced or augmented by asynchronous factory functions like `create_stripe_agent_toolkit(...)` in future major versions, especially for frameworks that benefit from async initialization.
  Fix: While `StripeAgentToolkit(...)` currently works, it's advisable to use the `create_stripe_agent_toolkit()` asynchronous factory function when available and appropriate for your agent framework, as shown in more recent quickstarts.

Install

• pip install stripe-agent-toolkit Install core package
• pip install stripe-agent-toolkit[openai,langchain,crewai,strands] Install with all optional dependencies

Imports

• StripeAgentToolkit

  from stripe_agent_toolkit.openai.toolkit import StripeAgentToolkit

  For OpenAI's Agent SDK integration, direct class import.
• StripeAgentToolkit

  from stripe_agent_toolkit.langchain.toolkit import StripeAgentToolkit

  For LangChain integration, direct class import.
• create_stripe_agent_toolkit

  from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit

  Asynchronous factory function for OpenAI Agent SDK. Recommended in recent examples.
• create_stripe_agent_toolkit

  from stripe_agent_toolkit.langchain.toolkit import create_stripe_agent_toolkit

  Asynchronous factory function for LangChain. Recommended in recent examples.
• create_stripe_agent_toolkit

  from stripe_agent_toolkit.ai_sdk import create_stripe_agent_toolkit

  For Vercel's AI SDK and Model Context Protocol (MCP) integrations.

Quickstart

This quickstart demonstrates how to initialize the `stripe-agent-toolkit` with your Stripe secret key and configure its available actions. It emphasizes the use of Restricted API Keys (rk_*) for enhanced security and outlines how to retrieve the tools that an AI agent can then utilize. The example includes a basic setup, indicating where an agent framework would integrate with the toolkit's provided tools, and strongly recommends setting the Stripe API key via environment variables.

import asyncio
import os
from stripe_agent_toolkit.openai.toolkit import create_stripe_agent_toolkit

async def main():
    # It is strongly recommended to use a Restricted API Key (rk_*) for better security.
    # Store your secret key securely, e.g., in an environment variable.
    stripe_secret_key = os.environ.get('STRIPE_SECRET_KEY', 'sk_test_YOUR_TEST_KEY')

    if not stripe_secret_key or stripe_secret_key == 'sk_test_YOUR_TEST_KEY':
        print("Warning: Please set the STRIPE_SECRET_KEY environment variable ",
              "or replace 'sk_test_YOUR_TEST_KEY' with a real (test) key.")
        return

    # Initialize the toolkit with your secret key and specify allowed actions.
    # Tool availability is determined by permissions on the restricted key.
    toolkit = await create_stripe_agent_toolkit(
        secret_key=stripe_secret_key,
        configuration={
            "actions": {
                "payment_links": {
                    "create": True
                }
            }
        }
    )

    try:
        tools = toolkit.get_tools()
        print(f"Available Stripe Agent Tools: {[tool.name for tool in tools]}")

        # Example: Integrate with an agent framework (e.g., OpenAI's Agent SDK or LangChain)
        # This part assumes an agent framework is set up to consume these tools.
        # For a full agent example, refer to the Stripe Agent Toolkit documentation.

        # In a real agent workflow, the agent would call these tools based on user prompts.
        # For demonstration, let's pretend to call a tool.
        if 'create_payment_link' in [tool.name for tool in tools]:
            print("\n'create_payment_link' tool is available. Your agent can now create payment links.")
            # Example of how an agent might use a tool (simplified representation):
            # agent_response = await agent.run("Create a payment link for a product 'Premium Widget' for $25.00.")
            # print(agent_response)

    finally:
        # Clean up resources when done.
        await toolkit.close()

if __name__ == "__main__":
    asyncio.run(main())