Introduction

Introduction

We recently announced our new open-source Agents SDK, designed to help you build agentic AI applications using a lightweight, easy-to-use package with minimal abstractions.

This cookbook demonstrates how you can leverage the Agents SDK in combination with Stripe's API to handle dispute management, a common operational challenge many businesses face. Specifically, we focus on two real-world scenarios:

1. Company Mistake:
   A scenario where the company clearly made an error, such as failing to fulfill an order, where accepting the dispute the appropriate action.

2. Customer Dispute (Final Sale):
   A scenario where a customer knowingly disputes a transaction despite receiving the correct item and understanding that the purchase was final sale, requiring further investigation to gather supporting evidence.

To address these scenarios, we'll introduce three distinct agents:

• Triage Agent:
  Determines whether to accept or escalate a dispute based on the fulfillment status of the order.

• Acceptance Agent:
  Handles clear-cut cases by automatically accepting disputes, providing concise reasoning.

• Investigator Agent:
  Performs thorough investigations into disputes by analyzing communication records and order information to collect essential evidence.

Throughout this cookbook, we’ll guide you step-by-step, illustrating how custom agentic workflows can automate dispute management and support your business operations.

Prerequisites

Before running this cookbook, you must set up the following accounts and complete a few setup actions. These prerequisites are essential to interact with the APIs used in this project.

1. OpenAI Account

• Purpose:
  You need an OpenAI account to access language models and use the Agents SDK featured in this cookbook.

• Action:
  Sign up for an OpenAI account if you don’t already have one. Once you have an account, create an API key by visiting the OpenAI API Keys page.

2. Stripe Account

• Purpose:
  A Stripe account is required to simulate payment processing, manage disputes, and interact with the Stripe API as part of our demo workflow.

• Action:
  Create a free Stripe account by visiting the Stripe Signup Page.

• Locate Your API Keys:
  Log in to your Stripe dashboard and navigate to Developers > API keys.

• Use Test Mode:
  Use your Test Secret Key for all development and testing.

3. Create a .env file with your OpenAI API and Stripe API Keys

OPENAI_API_KEY=
STRIPE_SECRET_KEY=

Environment Setup

First we will install the necessary dependencies, then import the libraries and write some utility functions that we will use later on.

Define Function Tools

This section defines several helper function tools that support the dispute processing workflow.

• get_order, get_phone_logs and get_emails simulate external data lookups by returning order details and email/phone records based on provided identifiers.
• retrieve_payment_intent interacts with the Stripe API to fetch payment intent details.
• close_dispute automatically closes a Stripe dispute using the provided dispute ID, ensuring that disputes are properly resolved and logged.

Define the Agents

• The Dispute Intake Agent (investigator_agent) is responsible for investigating disputes by gathering all relevant evidence and providing a report.
• The Accept a Dispute Agent (accept_dispute_agent) handles disputes that are determined to be valid by automatically closing them and providing a brief explanation for the decision.
• The Triage Agent (triage_agent) serves as the decision-maker by extracting the order ID from the payment intent's metadata, retrieving detailed order information, and then deciding whether to escalate the dispute to the investigator or to pass it to the accept dispute agent.
• Together, these agents form a modular workflow that automates and streamlines the dispute resolution process by delegating specific tasks to specialized agents.

Retrieve the Dispute and Initiate the Agentic Workflow

This function retrieves the dispute details from Stripe using the provided payment_intent_id and initiates the dispute-handling workflow by passing the retrieved dispute information to the specified triage_agent.

Scenario 1: Company Mistake (Product Not Received)

This scenario represents a situation where the company has clearly made an error—for instance, failing to fulfill or ship an order. In such cases, it may be appropriate to accept the dispute rather than contest it.

Scenario 2: Customer Dispute (Final Sale)

This scenario describes a situation where a customer intentionally disputes a transaction, despite having received the correct product and being fully aware that the purchase was clearly marked as a "final sale" (no refunds or returns). Such disputes typically require further investigation to collect evidence in order to effectively contest the dispute.

Conclusion

In this Jupyter Notebook, we explored the capabilities of the OpenAI Agents SDK, demonstrating how to efficiently create agent-based AI applications using a simple, Python-first approach. Specifically, we showcased the following SDK features:

• Agent Loop: Manages tool calls, communicates results to the LLM, and loops until completion.
• Handoffs: Enables coordination and delegation tasks between multiple specialized agents.
• Function Tools: Converts Python functions into tools with automatic schema generation and validation.

Additionally, the SDK offers built-in Tracing, accessible via the OpenAI dashboard. Tracing helps you visualize, debug, and monitor your agent workflows during both development and production phases. It also integrates smoothly with OpenAI’s evaluation, fine-tuning, and distillation tools.

While we didn't cover it directly in this notebook, implementing Guardrails is strongly recommended for production applications to validate inputs and proactively detect errors.

Overall, this notebook lays a clear foundation for further exploration, emphasizing how the OpenAI Agents SDK facilitates intuitive and effective agent-driven workflows.