Agent toolkit

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.

 from paypal_agent_toolkit.openai.toolkit import PayPalToolkit 
 from paypal_agent_toolkit.common.configuration import Configuration, Context

 configuration = Configuration(
     actions={
         "orders": {
             "create": True,
             "get": True,
             "capture": True,
         }
     },
     context=Context(
         sandbox=True
     )
 )

 # Initialize toolkit
 toolkit = 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.

 from agents import Agent

 tools = toolkit.get_tools()

 agent = Agent(
     name="PayPal Assistant",
     instructions="""
     You're a helpful assistant specialized in managing PayPal transactions:
     - To create orders, invoke create_order.
     - After approval by user, invoke capture_order.
     - To check an order status, invoke get_order_status. """, tools=tools )

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.

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 is still 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}.

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

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.

 from paypal_agent_toolkit.openai.toolkit import PayPalToolkit 
 from paypal_agent_toolkit.common.configuration import Configuration, Context

 configuration = Configuration(
     actions={
         "orders": {
             "create": True,
             "get": True,
             "capture": True,
         }
     },
     context=Context(
         sandbox=True
     )
 )

 # Initialize toolkit
 toolkit = 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.

 from agents import Agent

 tools = toolkit.get_tools()

 agent = Agent(
     name="PayPal Assistant",
     instructions="""
     You're a helpful assistant specialized in managing PayPal transactions:
     - To create orders, invoke create_order.
     - After approval by user, invoke capture_order.
     - To check an order status, invoke get_order_status. """, tools=tools )

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.

Best practices for commerce agents

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

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}.

Agent toolkit

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Agent toolkit

On this page

On this page