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. 

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.

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

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.

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.

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. 

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:

1. Start with the highest value agents. Begin with agents that address your most frequent customer interactions. 
2. Design clear agent boundaries and handoffs between agents and human staff. 
3. 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. 
4. 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. 
5. 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

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: 

1. create_invoice: Create an invoice for jane@example.com for 3 hours of CAD design at $100 per hour.
2. send_invoice: Send invoice {invoice_id} to the client.
3. 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:

1. create_order: Place an order for 2 “Custom Gold Ring” at $450 each (currency USD).
2. pay_order: Capture payment for order {order_id}.
3. 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:

1. create_product: Create a new product named “Coffee-Club Subscription” with the type of DIGITAL.
2. create_subscription_plan: Create a MONTH subscription plan for product {product_id} named “Monthly Roast Plan” at the price of 20 USD per month.
3. create_subscription: Create a subscription to plan {plan_id} for subscriber Alice Brown whose email address is alice@example.com.

Evaluate and resolve disputes

To manage disputes, you might use prompts like these:

1. list_disputes: List all OPEN disputes.
2. get_dispute: Get details for dispute {dispute_id}.
3. 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:

1. create_product: Create a new product called “Limited-Edition Walnut Serving Tray” of type PHYSICAL.
2. list_product: List all products (page 1, page_size 25).
3. 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: 

1. create_invoice: Create an invoice for bob@example.com for one 1 “Pop-up Booth Entry Fee” at 20 USD.
2. send_invoice: Send invoice {invoice_id}.
3. 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: 

1. cancel_sent_invoice: Cancel the SENT invoice with ID {invoice_id}.
2. create_invoice: Create a corrected invoice for dana@example.com: 4 h consulting at 90 USD/h.
3. send_invoice: Send invoice {new_invoice_id}.

Reconcile a transaction

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

1. list_transaction: List of my transactions for the last 14 days.
2. 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: 

1. show_subscription_details: Show the details for subscription ID {subscription_id}.
2. cancel_subscription: Cancel the subscription ID {subscription_id}.