Agent toolkit

Last updated: Apr 29th, 12:34pm

PayPal's agent toolkit is a library that incorporates PayPal API capabilities into AI agent workflows. This toolkit enables popular agent frameworks, such as OpenAI's Agents SDK, Vercel's AI SDK, Model Context Protocol (MCP), LangChain, and CrewAI, to integrate with PayPal APIs using function calling.

Key features

The agent toolkit from PayPal enables you to:

Integrate with PayPal APIs to access orders, invoices, subscriptions, shipment tracking, transaction details, and dispute management through pre-built functions.

Develop with your preferred tools, including:
- AI agent frameworks, like OpenAI's Agents SDK, Vercel's AI SDK, Model Context Protocol (MCP), LangChain, and CrewAI
- Multiple languages, including TypeScript and Python

Build custom agent capabilities to extend core PayPal features and connect with other toolkits to create multi-step agent workflows.

Set up your environment

To prepare for an integration, set up your environment first.

Download and install Node.js version 18 or later from the official Node.js website.

Run the command npm install @paypal/agent-toolkit to install the agent toolkit, or download the package from the GitHub repo.

You'll need your PayPal account's client ID and secret from PayPal Developer Dashboard to configure this library.

Integration

PayPal's agent toolkit supports OpenAI’s Agents SDK, Vercel’s AI SDK, and Model Context Protocol (MCP). It works with LLM providers that supports function calling and is compatible with TypeScript and Python.

For integration steps, see the corresponding topic for your AI platform in this guide.

For information about setting up the front end for testing any of these integrations, see the agent toolkit quickstart guide .

Complete the following steps to integrate PayPal's agent toolkit with OpenAI's Agents SDK. The agent toolkit works with Agents SDK, which passes it as a list of tools.

Import PayPal’s agent toolkit into your code.

Update your clientId and clientSecret with the values from PayPal Developer Dashboard.

1from paypal_agent_toolkit.openai.toolkit import PayPalToolkit
2from paypal_agent_toolkit.common.configuration import Configuration, Context
3
4configuration = Configuration(
5    actions={
6        "orders": {
7            "create": True,
8            "get": True,
9            "capture": True,
10        }
11    },
12    context=Context(
13        sandbox=True
14    )
15)
16
17# Initialize toolkit
18toolkit = PayPalToolkit(client_id=PAYPAL_CLIENT_ID, secret=PAYPAL_SECRET, configuration = configuration)

You can use the agent toolkit's functions and other tools as your integration requires.

1from agents import Agent
2
3tools = toolkit.get_tools()
4
5agent = Agent(
6    name="PayPal Assistant",
7    instructions="""
8    You're a helpful assistant specialized in managing PayPal transactions:
9    - To create orders, invoke create_order.
10    - After approval by user, invoke capture_order.
11    - To check an order status, invoke get_order_status.
12    """,
13    tools=tools
14)

Test the integration.

Available tools

PayPal's agent toolkit includes the following tools. We also provide some best practices for prompts and some examples of multistep prompts for common use cases after the lists of tools.

Catalog management

Functionality	Description	Parameters	Sample prompt
`create_product`	Create a new product in the PayPal catalog.	`name` (string, required): The name of the product `type` (string, required, enum): The type of the product. Allowed values are `['PHYSICAL', 'DIGITAL', 'SERVICE']`.	Create a new product with the name '{product_name}' of type '{product_type}'.
`list_product`	List products from the PayPal catalog. Pagination options are available.	`page` (number, optional): The specific page number to retrieve. The default behavior is to go to the first page. `page_size` (number, optional): The maximum number of products to return per page. The default behavior is to use a system-defined limit.	List all products.
`show_product_details`	Show details of a specific product from the PayPal catalog.	`product_id` (string, required): The ID of the product to retrieve	Show the details for product id {product_id}.

Dispute management

Functionality	Description	Parameters	Sample prompt
`list_disputes`	Retrieve a summary of all disputes with optional filtering.	`status` (string, optional): Filter disputes by status, such as OPEN or RESOLVED	List all {status} disputes.
`get_dispute`	Retrieve detailed information about a specific dispute.	`dispute_id` (string): The unique identifier of the dispute	Get details for dispute {dispute_id}.
`accept_dispute_claim`	Accept a dispute claim, resolving it in favor of the buyer.	`dispute_id` (string): The unique identifier of the dispute	Accept the dispute with ID {dispute_id}.

Invoices

Functionality	Description	Parameters	Sample prompt
`create_invoice`	Create a new invoice in the PayPal system.	`recipient_email`: Email address of the invoice recipient `items`: List of items or services to include in the invoice: `name` (string): Name of the item `quantity` (number): Quantity of the item `unit_price` (number): Price per unit of the item	Create an invoice for {customer_email} including 2 hours of consulting at $150 per hour.
`list_invoices`	List invoices. Pagination and filtering options are available.	`page` (number, optional): Page number for pagination `page_size` (number, optional): Number of invoices per page `status` (string, optional): Filter invoices by status (such as SENT or PAID)	List all {status} invoices on page {page} with {page_size} invoices per page.
`get_invoice`	Retrieve details about a specific invoice.	`invoice_id` (string): The unique identifier of the invoice	What are the details of invoice {invoice_id}?
`send_invoice`	Send an existing invoice to the specified recipient.	`invoice_id` (string): The unique identifier of the invoice to be sent	Send invoice {invoice_id} to the client.
`send_invoice_reminder`	Send a reminder for an existing invoice.	`invoice_id` (string): The unique identifier of the invoice	Send a reminder for invoice {invoice_id}.
`cancel_sent_invoice`	Cancel a sent invoice.	`invoice_id` (string): The unique identifier of the invoice to cancel	Cancel the sent invoice {invoice_id}.
`generate_invoice_qr_code`	Generate a QR code for an invoice.	`invoice_id` (string): The unique identifier of the invoice	Generate a QR code for invoice {invoice_id}.

Payments

Functionality	Description	Parameters	Sample prompt
`create_order`	Create an order in the PayPal system based on provided details.	`items` (array): List of items to include in the order each item should have: `name` (string): Name of the item `quantity` (number): Quantity of the item `unit_price` (number): Price per unit of the item `currency` (string): Currency code (e.g., USD, EUR)	Place an order for {quantity} units of '{item_name}' at ${unit_price} each.
`get_order`	Retrieve the details of an order.	`order_id` (string): The unique identifier of the order	Get details for order {order_id}.
`pay_order`	Capture payment for an authorized order.	`order_id` (string): The unique identifier of the order to capture	Capture payment for order {order_id}.

Shipment tracking

Functionality	Description	Parameters	Sample prompt
`create_shipment_tracking`	Create shipment tracking information for a PayPal transaction.	`tracking_number` (string, required): The tracking number for the shipment `transaction_id` (string, required): The transaction ID associated with the shipment `carrier` (string, required): The carrier handling the shipment, such as FEDEX or UPS `order_id`: (string, optional): The order ID for the shipment `status`: (string, optional, enum): The current status of the shipment. Allowed values are `['ON_HOLD', 'SHIPPED', 'DELIVERED', 'CANCELLED', 'LOCAL_PICKUP']`. The default value is `'SHIPPED'`.	Add tracking number '{tracking_number}' with carrier '{carrier}' to PayPal order ID {order_id}.
`get_shipment_tracking`	Get shipment tracking information for a specific shipment.	`order_id` (string, required): The order ID for the shipment `transaction_id` (string, optional): The transaction ID associated with the shipment	Get the tracking number for PayPal order ID {order_id}.

Reporting and insights

Functionality	Description	Parameters	Sample prompt
`list_transaction`	List all transactions. Pagination and filtering options are available.	`start_date` (string, optional): The start date for filtering transactions. The default value is 31 days. `end_date` (string, optional): The end date for filtering transactions	Get the list of my transactions for last {days} days.

Subscription management

Functionality	Description	Parameters	Sample prompt
`cancel_subscription`	Cancel an active subscription.	`subscription_id` (string, required): The ID of the subscription to cancel `Reason` (string, optional): Cancellation reason	Cancel the subscription id {subscription_id}.
`create_subscription`	Create a new subscription.	`plan_id` (string, required): The ID of the subscription plan `Subscriber` (array, optional): The subscriber request information: `name` (string, optional): The name of the subscriber `email` (string, optional): The email address of the subscriber	Create a subscription for plan id {plan_id} with subscriber name as {subscriber_name} with email address {subscriber_email}.
`create_subscription_plan`	Creates a new subscription plan.	`product_id` (string, required): The ID of the subscription plan `name` (string, required): The plan name `billing_cycles` (array, required): An array of billing cycles for trial billing and regular billing. A plan can have at most 2 trial cycles and only 1 regular cycle. `tenure_type` (string, required): The type of billing cycle, `[REGULAR\|TRIAL]` `sequence` (integer, required): The order in which to run this cycle among other billing cycles `frequency` (integer, required): The frequency details for this billing cycle `interval_unit` (string, required): The interval at which the subscription is charged or billed: `[DAY\|WEEK\|MONTH\|YEAR]` `payment_preferences` (array, required): The payment preferences for a subscription `auto_bill_outstanding` (boolean, optional): Indicator of whether to automatically bill the outstanding amount in the next billing cycle. The default value is true.	Create a {interval_unit} PayPal subscription plan for product '{product_name}' with billing cycle '{billing_cycle}', price '{price} {currency}'. Set trial period cycle to '{trial_period}'.
`list_subscription_plans`	List subscription plans.	`product_id` (number, optional): List the subscription plans for a specific product `page` (number, optional): The specific page number to retrieve. The default behavior is to go to the first page. `page_size` (number, optional): The maximum number of products to return for each page. The default behavior is to use a system-defined limit.	List all subscription plans.
`show_subscription_details`	Show details of a specific subscription.	`subscription_id` (string, required): The ID of the subscription to retrieve	Show the details for subscription id {subscription_id}.
`show_subscription_plan_details`	Show details of a specific subscription plan.	`billing_plan_id` (string, required): The ID of the subscription plan to retrieve	Show the details for plan id {billing_plan_id}.

Best practices for commerce agents

When you implement them strategically, AI agents can enhance your business by providing consistent support, personalized recommendations, and streamlined processes. The key is maintaining the balance between automation efficiency and the human touch that customers value. With the right set of agents, you can automate customer interactions, streamline operations, and enhance overall customer experience while keeping human oversight where it matters most. Here is a practical guide for implementing AI agents to support your store.

Getting started

When you hire an employee, you consider that person’s scope, role, and responsibilities. Similarly, when building an agent, you keep the same things in mind.

Recommended best practices and considerations include:

Create an organizational chart based on roles and scope of responsibilities for your business.

Define a clear purpose for each agent and their role.

Define clear capabilities and responsibilities for each agent.

Define where an agent should interact with another agent.

Clearly define edge cases and expectations of how an Agent should handle these.

Define where an agent hands off to a human.

Understand where agents need to be integrated to perform effectively, such as with an inventory management system.

Examples of agent types for an online store

These examples are for a a fictional online coffee bean store, but they illustrate some of the ways that any seller might use agents.

Agent type	Purpose	Key capabilities
Customer support	Handle common customer inquiries and support requests.	Answer product questions, such as coffee origins, roast levels, or flavor profiles. Process order status inquiries. Explain shipping policies and timeframes. Handle basic troubleshooting for website or order issues.
Product recommendation	Help customers discover coffee beans that suit their preferences	Ask questions about taste preferences, such as acidity, body, and flavor notes. Consider brewing methods, such as French press, espresso, or pour-over. Suggest complementary products, such as filters or brewing equipment. Track and learn from customer patterns.
Order processing	Streamline the purchase process and handle order-related tasks.	Guide customers through checkout. Process shipping address validation. Handle inventory checks and back-order information. Provide shipping cost estimates and delivery timeframes.
Shipping	Automate processing of end-to-end shipping capabilities.	Search open orders, and generate shipping labels. Print shipping labels. Share shipping tracking information with customers and partners. Interact with a returns agent to generate return shipping labels.
Returns and exchanges	Facilitate smooth return and exchange processes.	Process return requests, and generate return labels. Explain return policies and eligibility. Process refunds or store credits. Gather feedback about reasons for returns.
Subscription management	Handle coffee subscription services and recurring orders.	Process subscription sign-ups and modifications. Handle requests to pause or resume a subscription. Manage delivery frequency changes. Process subscription cancellations with retention options.

Integration considerations

From the preceding examples, you can see how agents help automate an entire business, but there still is a cost consideration when implementing. Consider the size and scale of your business and your pain points to determine where it makes sense to invest in building an agent. Other cost considerations to factor in are the costs of tokens and how many tokens an AI agent uses to complete its tasks.

If you're thinking about using agents:

Start with the highest value agents. Begin with agents that address your most frequent customer interactions.
Design clear agent boundaries and handoffs between agents and human staff.
Develop a knowledge base. Ensure that you have a clearly documented knowledge base on products, FAQ’s, policies around shipping and returns, and so on. This knowledge base helps guide your agents.
Test and iterate. Commit the necessary time and resources for testing agents with real-world scenarios before full deployment to ensure accuracy and to allow you to improve the agent and its capabilities.
Monitor performance. Track the performance of an agent and your customer satisfaction to understand where agents are most effective and where they can be improved.

Agent-to-agent interactions

Another area to consider is how an agent interacts with other agents you build. These interactions help scope each agent’s role and prevent duplication or overlap.

Some examples of these interactions might include:

Order agent interacting with a shipping agent to quote shipping timelines
Returns agent interacting with a shipping agent to generate a return shipping label
Support agent interacting with a return agent to update the status of a return

Other integration considerations

Are your agents able to integrate into your other back-end systems to be effective? Consider how interactions like these might impact your agents and your integration:

Inventory management system for real-time stock levels
Order processing system for status updates
Customer accounts for personalized experiences
Shipping partners for tracking information
CRM system for customer history

Best practices for prompt engineering

Principle	Usage
Be clear about what to do and how to do it.	Put the action first (“Create an invoice…”), then supply parameter values in the order the tool expects.
Be specific.	Include every required field, such as `currency` and `invoice_id`. Unclear input can cause failure.
Separate complex tasks into simple ones.	For example, if you want to create a checkout sequence, you might have 3 subtasks: Create order. Pay order. Create shipment.
Encourage the agent to "think."	Begin an analytic request with a statement like “Think step-by-step before calling the tool…”. This can help the agent to avoid making bad calls.
Protect personally identifiable information (PII).	Never embed card numbers, personal financial information like social security numbers (SSNs), passwords, or secrets in prompts. The agent toolkit will reject this information, and you might violate the Payment Card Industry Data Security Standard (PCI DSS).

Multistep agent prompt examples

The following examples provide ideas for how to form multistep prompts for some standard use cases.

Invoice a client

To invoice a client, you might have steps like these:

create_invoice: Create an invoice for [email protected] for 3 hours of CAD design at $100 per hour.

send_invoice: Send invoice {invoice_id} to the client.

send_invoice_reminder: Send a reminder for invoice {invoice_id}.

Create an online order with payment and tracking

For an online order with shipping, you might use these steps in your prompts:

create_order: Place an order for 2 “Custom Gold Ring” at $450 each (currency USD).

pay_order: Capture payment for order {order_id}.

create_shipment_tracking: Add tracking 1Z999AA10123456784 with carrier UPS to order {order_id}.

Sell a subscription

Subscriptions are a type of product, which come with specific parameters. To sell subscriptions, you might complete these tasks using your agent tools:

create_product: Create a new product named “Coffee-Club Subscription” with the type of DIGITAL.

create_subscription_plan: Create a MONTH subscription plan for product {product_id} named “Monthly Roast Plan” at the price of 20 USD per month.

create_subscription: Create a subscription to plan {plan_id} for subscriber Alice Brown whose email address is [email protected].

Evaluate and resolve disputes

To manage disputes, you might use prompts like these:

list_disputes: List all OPEN disputes.

get_dispute: Get details for dispute {dispute_id}.

accept_dispute_claim: Accept the dispute with ID {dispute_id}.

Add and confirm the details for a new product

When you add a new product, you'll want to confirm that the product appears where and how it should. These prompts would do that:

create_product: Create a new product called “Limited-Edition Walnut Serving Tray” of type PHYSICAL.

list_product: List all products (page 1, page_size 25).

show_product_details: Show the details for product {product_id}.

Create an invoice and use a QR code for payment

This example shows how to invoice a client and use a QR code for on-site payment. To complete this sort of process, you might use the following tools and steps:

create_invoice: Create an invoice for [email protected] for one 1 “Pop-up Booth Entry Fee” at 20 USD.

send_invoice: Send invoice {invoice_id}.

generate_invoice_qr_code: Generate a QR code for invoice {invoice_id}.

Fix an invoice error

Correcting an invoice error might require steps like these:

cancel_sent_invoice: Cancel the SENT invoice with ID {invoice_id}.

create_invoice: Create a corrected invoice for [email protected]: 4 h consulting at 90 USD/h.

send_invoice: Send invoice {new_invoice_id}.

Reconcile a transaction

To reconcile a transaction, compare the order details to the transaction itself:

list_transaction: List of my transactions for the last 14 days.

get_order: Get the details for order {order_id}.

Cancel a subscription

If a user wants to cancel a subscription, you might need to check the terms of their subscription. To do that, you could use these steps:

show_subscription_details: Show the details for subscription ID {subscription_id}.

cancel_subscription: Cancel the subscription ID {subscription_id}.