jim/openai-cookbook
1
0
Fork 0
mirror of https://github.com/james-m-jordan/openai-cookbook.git synced 2025-05-09 19:32:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
openai-cookbook/examples/agents_sdk/dispute_agent.ipynb

493 lines
21 KiB
Plaintext
Raw Permalink Normal View History

Add Cookbook: Using the OpenAI Agents SDK to Automate Stripe Dispute Responses (#1724)
2025-03-19 15:43:41 -04:00
{
"cells": [
{
"cell_type": "markdown",
"id": "668c381f-e6d3-4404-bec5-81404a70bcb5",
"metadata": {},
"source": [
"# Introduction\n",
"\n",
"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.\n",
"\n",
"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:\n",
"\n",
"1. **Company Mistake:** \n",
" A scenario where the company clearly made an error, such as failing to fulfill an order, where accepting the dispute the appropriate action.\n",
"\n",
"2. **Customer Dispute (Final Sale):** \n",
" 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.\n",
"\n",
"To address these scenarios, we'll introduce three distinct agents:\n",
"\n",
"- **Triage Agent:** \n",
" Determines whether to accept or escalate a dispute based on the fulfillment status of the order.\n",
"\n",
"- **Acceptance Agent:** \n",
" Handles clear-cut cases by automatically accepting disputes, providing concise reasoning.\n",
"\n",
"- **Investigator Agent:** \n",
"Performs thorough investigations into disputes by analyzing communication records and order information to collect essential evidence.\n",
"\n",
"Throughout this cookbook, we’ll guide you step-by-step, illustrating how custom agentic workflows can automate dispute management and support your business operations.\n"
]
},
{
"cell_type": "markdown",
"id": "e4508e3f-520e-4294-bb73-aac2ecfcaf6b",
"metadata": {},
"source": [
"## Prerequisites\n",
"\n",
"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.\n",
"\n",
"#### 1. OpenAI Account\n",
"\n",
"- **Purpose:** \n",
" You need an OpenAI account to access language models and use the Agents SDK featured in this cookbook.\n",
"\n",
"- **Action:** \n",
" [Sign up for an OpenAI account](https://openai.com) if you don’t already have one. Once you have an account, create an API key by visiting the [OpenAI API Keys page](https://platform.openai.com/api-keys).\n",
"\n",
"#### 2. Stripe Account\n",
"\n",
"- **Purpose:** \n",
" A Stripe account is required to simulate payment processing, manage disputes, and interact with the Stripe API as part of our demo workflow.\n",
"\n",
"- **Action:** \n",
" Create a free Stripe account by visiting the [Stripe Signup Page](https://dashboard.stripe.com/register).\n",
"\n",
"- **Locate Your API Keys:** \n",
" Log in to your Stripe dashboard and navigate to **Developers > API keys**.\n",
"\n",
"- **Use Test Mode:** \n",
" Use your **Test Secret Key** for all development and testing.\n",
"\n",
"\n",
"#### 3. Create a .env file with your OpenAI API and Stripe API Keys\n",
"\n",
"```\n",
"OPENAI_API_KEY=\n",
"STRIPE_SECRET_KEY=\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "e5daf08c-d8fb-402c-b2c7-b89996ce97f0",
"metadata": {},
"source": [
"### Environment Setup\n",
"First we will install the necessary dependencies, then import the libraries and write some utility functions that we will use later on."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2e34c8bb-7720-432b-b0bc-d10414b6a65e",
"metadata": {},
"outputs": [],
"source": [
"%pip install python-dotenv --quiet\n",
"%pip install openai-agents --quiet\n",
"%pip install stripe --quiet\n",
"%pip install typing_extensions --quiet"
]
},
{
"cell_type": "code",
"execution_count": 211,
"id": "8cc88805-6473-458c-b745-c9f338ce8f19",
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"import logging\n",
"import json\n",
"from dotenv import load_dotenv\n",
"from agents import Agent, Runner, function_tool # Only import what you need\n",
"import stripe\n",
"from typing_extensions import TypedDict, Any\n",
"# Load environment variables from .env file\n",
"load_dotenv()\n",
"\n",
"# Configure logging\n",
"logging.basicConfig(level=logging.INFO)\n",
"logger = logging.getLogger(__name__)\n",
"\n",
"# Set Stripe API key from environment variables\n",
"stripe.api_key = os.getenv(\"STRIPE_SECRET_KEY\")"
]
},
{
"cell_type": "markdown",
"id": "736c9314-a51d-4bc2-aa5e-a40f01bdb836",
"metadata": {},
"source": [
"#### Define Function Tools\n",
"This section defines several helper function tools that support the dispute processing workflow. \n",
"<br>\n",
" \n",
"- `get_order`, `get_phone_logs` and `get_emails` simulate external data lookups by returning order details and email/phone records based on provided identifiers.\n",
"- `retrieve_payment_intent` interacts with the Stripe API to fetch payment intent details.\n",
"- `close_dispute` automatically closes a Stripe dispute using the provided dispute ID, ensuring that disputes are properly resolved and logged.\n"
]
},
{
"cell_type": "code",
"execution_count": 212,
"id": "1c04ec7b-c78a-4860-b940-75401f1f0153",
"metadata": {},
"outputs": [],
"source": [
"@function_tool\n",
"def get_phone_logs(phone_number: str) -> list:\n",
" \"\"\"\n",
" Return a list of phone call records for the given phone number.\n",
" Each record might include call timestamps, durations, notes, \n",
" and an associated order_id if applicable.\n",
" \"\"\"\n",
" phone_logs = [\n",
" {\n",
" \"phone_number\": \"+15551234567\",\n",
" \"timestamp\": \"2023-03-14 15:24:00\",\n",
" \"duration_minutes\": 5,\n",
" \"notes\": \"Asked about status of order #1121\",\n",
" \"order_id\": 1121\n",
" },\n",
" {\n",
" \"phone_number\": \"+15551234567\",\n",
" \"timestamp\": \"2023-02-28 10:10:00\",\n",
" \"duration_minutes\": 7,\n",
" \"notes\": \"Requested refund for order #1121, I told him we were unable to refund the order because it was final sale\",\n",
" \"order_id\": 1121\n",
" },\n",
" {\n",
" \"phone_number\": \"+15559876543\",\n",
" \"timestamp\": \"2023-01-05 09:00:00\",\n",
" \"duration_minutes\": 2,\n",
" \"notes\": \"General inquiry; no specific order mentioned\",\n",
" \"order_id\": None\n",
" },\n",
" ]\n",
" return [\n",
" log for log in phone_logs if log[\"phone_number\"] == phone_number\n",
" ]\n",
"\n",
"\n",
"@function_tool\n",
"def get_order(order_id: int) -> str:\n",
" \"\"\"\n",
" Retrieve an order by ID from a predefined list of orders.\n",
" Returns the corresponding order object or 'No order found'.\n",
" \"\"\"\n",
" orders = [\n",
" {\n",
" \"order_id\": 1234,\n",
" \"fulfillment_details\": \"not_shipped\"\n",
" },\n",
" {\n",
" \"order_id\": 9101,\n",
" \"fulfillment_details\": \"shipped\",\n",
" \"tracking_info\": {\n",
" \"carrier\": \"FedEx\",\n",
" \"tracking_number\": \"123456789012\"\n",
" },\n",
" \"delivery_status\": \"out for delivery\"\n",
" },\n",
" {\n",
" \"order_id\": 1121,\n",
" \"fulfillment_details\": \"delivered\",\n",
" \"customer_id\": \"cus_PZ1234567890\",\n",
" \"customer_phone\": \"+15551234567\",\n",
" \"order_date\": \"2023-01-01\",\n",
" \"customer_email\": \"customer1@example.com\",\n",
" \"tracking_info\": {\n",
" \"carrier\": \"UPS\",\n",
" \"tracking_number\": \"1Z999AA10123456784\",\n",
" \"delivery_status\": \"delivered\"\n",
" },\n",
" \"shipping_address\": {\n",
" \"zip\": \"10001\"\n",
" },\n",
" \"tos_acceptance\": {\n",
" \"date\": \"2023-01-01\",\n",
" \"ip\": \"192.168.1.1\"\n",
" }\n",
" }\n",
" ]\n",
" for order in orders:\n",
" if order[\"order_id\"] == order_id:\n",
" return order\n",
" return \"No order found\"\n",
"\n",
"\n",
"@function_tool\n",
"def get_emails(email: str) -> list:\n",
" \"\"\"\n",
" Return a list of email records for the given email address.\n",
" \"\"\"\n",
" emails = [\n",
" {\n",
" \"email\": \"customer1@example.com\",\n",
" \"subject\": \"Order #1121\",\n",
" \"body\": \"Hey, I know you don't accept refunds but the sneakers don't fit and I'd like a refund\"\n",
" },\n",
" {\n",
" \"email\": \"customer2@example.com\",\n",
" \"subject\": \"Inquiry about product availability\",\n",
" \"body\": \"Hello, I wanted to check if the new model of the smartphone is available in stock.\"\n",
" },\n",
" {\n",
" \"email\": \"customer3@example.com\",\n",
" \"subject\": \"Feedback on recent purchase\",\n",
" \"body\": \"Hi, I recently purchased a laptop from your store and I am very satisfied with the product. Keep up the good work!\"\n",
" }\n",
" ]\n",
" return [email_data for email_data in emails if email_data[\"email\"] == email]\n",
"\n",
"\n",
"@function_tool\n",
"async def retrieve_payment_intent(payment_intent_id: str) -> dict:\n",
" \"\"\"\n",
" Retrieve a Stripe payment intent by ID.\n",
" Returns the payment intent object on success or an empty dictionary on failure.\n",
" \"\"\"\n",
" try:\n",
" return stripe.PaymentIntent.retrieve(payment_intent_id)\n",
" except stripe.error.StripeError as e:\n",
" logger.error(f\"Stripe error occurred while retrieving payment intent: {e}\")\n",
" return {}\n",
"\n",
"@function_tool\n",
"async def close_dispute(dispute_id: str) -> dict:\n",
" \"\"\"\n",
" Close a Stripe dispute by ID. \n",
" Returns the dispute object on success or an empty dictionary on failure.\n",
" \"\"\"\n",
" try:\n",
" return stripe.Dispute.close(dispute_id)\n",
" except stripe.error.StripeError as e:\n",
" logger.error(f\"Stripe error occurred while closing dispute: {e}\")\n",
" return {}\n"
]
},
{
"cell_type": "markdown",
"id": "38e7a7ad-59fa-4096-8c2b-ffa3e2c295a9",
"metadata": {},
"source": [
"### Define the Agents\n",
"\n",
"- The **Dispute Intake Agent (investigator_agent)** is responsible for investigating disputes by gathering all relevant evidence and providing a report.\n",
"- 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.\n",
"- 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.\n",
"- Together, these agents form a modular workflow that automates and streamlines the dispute resolution process by delegating specific tasks to specialized agents.\n"
]
},
{
"cell_type": "code",
"execution_count": 213,
"id": "e4d20626-7ff2-4dac-9bb4-7b7af8b03add",
"metadata": {},
"outputs": [],
"source": [
"investigator_agent = Agent(\n",
" name=\"Dispute Intake Agent\",\n",
" instructions=(\n",
" \"As a dispute investigator, please compile the following details in your final output:\\n\\n\"\n",
" \"Dispute Details:\\n\"\n",
" \"- Dispute ID\\n\"\n",
" \"- Amount\\n\"\n",
" \"- Reason for Dispute\\n\"\n",
" \"- Card Brand\\n\\n\"\n",
" \"Payment & Order Details:\\n\"\n",
" \"- Fulfillment status of the order\\n\"\n",
" \"- Shipping carrier and tracking number\\n\"\n",
" \"- Confirmation of TOS acceptance\\n\\n\"\n",
" \"Email and Phone Records:\\n\"\n",
" \"- Any relevant email threads (include the full body text)\\n\"\n",
" \"- Any relevant phone logs\\n\"\n",
" ),\n",
" model=\"o3-mini\",\n",
" tools=[get_emails, get_phone_logs]\n",
")\n",
"\n",
"\n",
"accept_dispute_agent = Agent(\n",
" name=\"Accept Dispute Agent\",\n",
" instructions=(\n",
" \"You are an agent responsible for accepting disputes. Please do the following:\\n\"\n",
" \"1. Use the provided dispute ID to close the dispute.\\n\"\n",
" \"2. Provide a short explanation of why the dispute is being accepted.\\n\"\n",
" \"3. Reference any relevant order details (e.g., unfulfilled order, etc.) retrieved from the database.\\n\\n\"\n",
" \"Then, produce your final output in this exact format:\\n\\n\"\n",
" \"Dispute Details:\\n\"\n",
" \"- Dispute ID\\n\"\n",
" \"- Amount\\n\"\n",
" \"- Reason for Dispute\\n\\n\"\n",
" \"Order Details:\\n\"\n",
" \"- Fulfillment status of the order\\n\\n\"\n",
" \"Reasoning for closing the dispute\\n\"\n",
" ),\n",
" model=\"gpt-4o\",\n",
" tools=[close_dispute]\n",
")\n",
"\n",
"triage_agent = Agent(\n",
" name=\"Triage Agent\",\n",
" instructions=(\n",
" \"Please do the following:\\n\"\n",
" \"1. Find the order ID from the payment intent's metadata.\\n\"\n",
" \"2. Retrieve detailed information about the order (e.g., shipping status).\\n\"\n",
" \"3. If the order has shipped, escalate this dispute to the investigator agent.\\n\"\n",
" \"4. If the order has not shipped, accept the dispute.\\n\"\n",
" ),\n",
" model=\"gpt-4o\",\n",
" tools=[retrieve_payment_intent, get_order],\n",
" handoffs=[accept_dispute_agent, investigator_agent],\n",
")\n"
]
},
{
"cell_type": "markdown",
"id": "b31c1be3-0360-42c1-93fa-d551cca9a43e",
"metadata": {},
"source": [
"#### Retrieve the Dispute and Initiate the Agentic Workflow\n",
"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`.\n"
]
},
{
"cell_type": "code",
"execution_count": 214,
"id": "5eaaa982-80fa-4018-8b9d-e73e90f8ae0f",
"metadata": {},
"outputs": [],
"source": [
"async def process_dispute(payment_intent_id, triage_agent):\n",
" \"\"\"Retrieve and process dispute data for a given PaymentIntent.\"\"\"\n",
" disputes_list = stripe.Dispute.list(payment_intent=payment_intent_id)\n",
" if not disputes_list.data:\n",
" logger.warning(\"No dispute data found for PaymentIntent: %s\", payment_intent_id)\n",
" return None\n",
" \n",
" dispute_data = disputes_list.data[0]\n",
" \n",
" relevant_data = {\n",
" \"dispute_id\": dispute_data.get(\"id\"),\n",
" \"amount\": dispute_data.get(\"amount\"),\n",
" \"due_by\": dispute_data.get(\"evidence_details\", {}).get(\"due_by\"),\n",
" \"payment_intent\": dispute_data.get(\"payment_intent\"),\n",
" \"reason\": dispute_data.get(\"reason\"),\n",
" \"status\": dispute_data.get(\"status\"),\n",
" \"card_brand\": dispute_data.get(\"payment_method_details\", {}).get(\"card\", {}).get(\"brand\")\n",
" }\n",
" \n",
" event_str = json.dumps(relevant_data)\n",
" # Pass the dispute data to the triage agent\n",
" result = await Runner.run(triage_agent, input=event_str)\n",
" logger.info(\"WORKFLOW RESULT: %s\", result.final_output)\n",
" \n",
" return relevant_data, result.final_output"
]
},
{
"cell_type": "markdown",
"id": "83fe5866-84ec-420a-9841-49ef88f91670",
"metadata": {},
"source": [
"#### Scenario 1: Company Mistake (Product Not Received)\n",
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "57274ad2-e524-40a4-9eb8-4413bdf54c6f",
"metadata": {},
"outputs": [],
"source": [
"payment = stripe.PaymentIntent.create(\n",
" amount=2000,\n",
" currency=\"usd\",\n",
" payment_method = \"pm_card_createDisputeProductNotReceived\",\n",
" confirm=True,\n",
" metadata={\"order_id\": \"1234\"},\n",
" off_session=True,\n",
" automatic_payment_methods={\"enabled\": True},\n",
")\n",
"relevant_data, triage_result = await process_dispute(payment.id, triage_agent)"
]
},
{
"cell_type": "markdown",
"id": "d4a48e55-2c08-4563-8a25-1d2e5d97bb33",
"metadata": {},
"source": [
"#### Scenario 2: Customer Dispute (Final Sale)\n",
"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."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f6aafea1-72c2-42fd-a78a-e494804b5dde",
"metadata": {},
"outputs": [],
"source": [
"payment = stripe.PaymentIntent.create(\n",
" amount=2000,\n",
" currency=\"usd\",\n",
" payment_method = \"pm_card_createDispute\",\n",
" confirm=True,\n",
" metadata={\"order_id\": \"1121\"},\n",
" off_session=True,\n",
" automatic_payment_methods={\"enabled\": True},\n",
")\n",
"relevant_data, triage_result = await process_dispute(payment.id, triage_agent)"
]
},
{
"cell_type": "markdown",
"id": "ec050259",
"metadata": {},
"source": [
"## Conclusion\n",
"\n",
"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:\n",
"\n",
"- **Agent Loop**: Manages tool calls, communicates results to the LLM, and loops until completion.\n",
"- **Handoffs**: Enables coordination and delegation tasks between multiple specialized agents.\n",
"- **Function Tools**: Converts Python functions into tools with automatic schema generation and validation.\n",
"\n",
"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.\n",
"\n",
"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.\n",
"\n",
"Overall, this notebook lays a clear foundation for further exploration, emphasizing how the OpenAI Agents SDK facilitates intuitive and effective agent-driven workflows."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.2"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
Reference in New Issue Copy Permalink