spelling

Author: moustafa-openai

examples/agents_sdk/AI_Research_Assistant_Cookbook.ipynb

@@ -5,11 +5,11 @@
    "id": "85b66af9",
    "metadata": {},
    "source": [
-    "# Building an **AI Research Assistant** with the OpenAI Agents SDK\n",
+    "# Build a **Multi‑Agent AI Research Assistant** with the OpenAI Agents SDK & Responses API\n",
     "\n",
     "This notebook provides a reference patterns for implementing a multi‑agent AI Research Assistant that can plan, search, curate, and draft high‑quality reports with citations.\n",
     "\n",
-    "While the Deep Research feature is avaialble in ChatGPT, however, individual and companies may want to implement their own API based solution for a more finegrained control over the output.\n",
+    "While the Deep Research feature is available in ChatGPT, however, individual and companies may want to implement their own API based solution for a more fine grained control over the output.\n",
     "\n",
     "With support for Agents, and built-in tools such as Code Interpreter, Web Search, and File Search, - Responses API makes building your own Research Assistant fast and easy. "
    ]
@@ -60,7 +60,7 @@
     "|------|---------|-------|\n",
     "| **Query Expansion** | Draft multi‑facet prompts / hypotheses | `o4-mini` |\n",
     "| **Search‑Term Generation** | Expand/clean user query into rich keyword list | `gpt‑4.1` |\n",
-    "| **Conduct Research** | Run web & internal searches, rank & summarise results | `gpt‑4.1` + tools |\n",
+    "| **Conduct Research** | Run web & internal searches, rank & summarize results | `gpt‑4.1` + tools |\n",
     "| **Draft Report** | Produce first narrative with reasoning & inline citations | `o3` |\n",
     "| **Report Expansion** | Polish formatting, add charts / images / appendix | `gpt‑4.1` + tools |"
    ]
@@ -75,7 +75,7 @@
     "\n",
     "* **Research Planning Agent** – interprets the user request and produces a research plan/agenda.\n",
     "* **Knowledge Assistant Agent** – orchestrates parallel web & file searches via built‑in tools, curates short‑term memory.\n",
-    "* **Web Search Agent(s)** – perform Internet queries, deduplicate, rank and summarise pages.\n",
+    "* **Web Search Agent(s)** – perform Internet queries, deduplicate, rank and summarize pages.\n",
     "* **Report Creation Agent** – consumes curated corpus and drafts the structured report.\n",
     "* **(Optional) Data Analysis Agent** – executes code for numeric/CSV analyses via the Code Interpreter tool.\n",
     "* **(Optional) Image‑Gen Agent** – generates illustrative figures.\n",
@@ -131,9 +131,9 @@
     "\n",
     "The query expansion step ensures the subsequent agents conducting research have sufficient context of user's inquiry. \n",
     "\n",
-    "The first step is to understand user's intent, and make sure the user has provided sufficinet details for subsequent agents to search the web, build a knowledge repository, and prepare a deepdive report. The `query_expansion_agent.py` accomplishes this with the prompt that outlines minimum information needed from the user to generate a report. This could include timeframe, industry, target audience, etc. The prompt can be tailored to the need of your deepresearch assistant. The agent will put a `is_task_clear` yes or no, when its no, it would prompt the user with additional questions, if sufficent information is available, it would output the expanded prompt. \n",
+    "The first step is to understand user's intent, and make sure the user has provided sufficient details for subsequent agents to search the web, build a knowledge repository, and prepare a deep dive report. The `query_expansion_agent.py` accomplishes this with the prompt that outlines minimum information needed from the user to generate a report. This could include timeframe, industry, target audience, etc. The prompt can be tailored to the need of your deep research assistant. The agent will put a `is_task_clear` yes or no, when its no, it would prompt the user with additional questions, if sufficient information is available, it would output the expanded prompt. \n",
     "\n",
-    "This is also an opportunity to enforce input guardrails for any research topics that you'd like to restrict the user from reserarching based on your usage policies. "
+    "This is also an opportunity to enforce input guardrails for any research topics that you'd like to restrict the user from researching based on your usage policies. "
    ]
   },
   {
@@ -142,7 +142,7 @@
    "metadata": {},
    "source": [
     "##### Input Guardrails with Agents SDK \n",
-    "Let's assume our ficticious guardrail is to prevent the user from generating a non-AI releated topic report. For this we will define a guardrail agent. The guardrail agent `topic_guradrail.py` checks whether the topic is related to AI, if not, it raises an execption. The function `ai_topic_guardrail` is passed to the `QueryExpansionAgent()` as `input_guardrails`"
+    "Let's assume our fictitious guardrail is to prevent the user from generating a non-AI related topic report. For this we will define a guardrail agent. The guardrail agent `topic_content_guardrail.py` checks whether the topic is related to AI, if not, it raises an exception. The function `ai_topic_guardrail` is passed to the `QueryExpansionAgent()` as `input_guardrails`"
    ]
   },
   {
@@ -249,7 +249,7 @@
    "source": [
     "Conducting Web search is typically an integral part of the deep research process. First we generate web search terms relevant to the research report. In the next step we will search the web and build a knowledge repository of the data.\n",
     "\n",
-    "The `WebSearchTermsGenerationAgent` takes as input the the expanded prompt, and generates succient search terms. You can structure the search term generation prompt according to your user's typical requirements such as include adjacent industries in the search terms, include competitors, etc. Additionally, you can also control how much data you want to gather e.g., number of search terms to generate. In our case, we will limit to 3 search terms. "
+    "The `WebSearchTermsGenerationAgent` takes as input the the expanded prompt, and generates succinct search terms. You can structure the search term generation prompt according to your user's typical requirements such as include adjacent industries in the search terms, include competitors, etc. Additionally, you can also control how much data you want to gather e.g., number of search terms to generate. In our case, we will limit to 3 search terms. "
    ]
   },
   {
@@ -286,19 +286,21 @@
    "id": "3feeaae8",
    "metadata": {},
    "source": [
-    "#### Step 3 - Scroll the Web build a inventory of data sources \n",
+    "### Step 3 - Web Search: Build an Inventory of Data Sources\n",
     "\n",
-    "We will use custom web search to identify and knowledge content to form the baseline for our report. You can learn more about building custom web search and retreival here. [Building a Bring Your Own Browser (BYOB) Tool for Web Browsing and Summarization](https://cookbook.openai.com/examples/third_party/web_search_with_google_api_bring_your_own_browser_tool). You will also need a Google Custom Search API key and Custom Search Engine ID (CSE ID) in a .env file at the root. \n",
+    "In this step, we will use the OpenAI web search tool that is integrated into the `responses` API to identify and collect knowledge content that will form the baseline for our report. This tool allows you to search the web and retrieve relevant information and citations directly within your workflow, without needing to set up any external search APIs or browser automation.\n",
     "\n",
-    "NOTE: The reason for using custom web search is provide more finegrained control over which information is retreived, and guardrails such as excluding competitor's content from your report. \n",
+    "You can learn more about the OpenAI web search tool here: [OpenAI Web Search Tool Documentation](https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses).\n",
     "\n",
-    "This is a 3 step process: \n",
+    "The OpenAI web search tool is a convenient, out-of-the-box solution for most research use cases. However, if you require more fine-grained control over the information retrieved (for example, to exclude certain sources, apply custom filters, or use a specific search engine), you can also build and use your own browser-based or Google Custom Search integration. For an example of building a custom web search and retrieval pipeline, see [Building a Bring Your Own Browser (BYOB) Tool for Web Browsing and Summarization](https://cookbook.openai.com/examples/third_party/web_search_with_google_api_bring_your_own_browser_tool).\n",
     "\n",
-    "1. Obtain the search results (top 10 pages)\n",
-    "2. Scroll the pages, and summarize the key points \n",
-    "3. Output guardrails to weedout irrelevant or undesirable results (e.g., the timeframe of the content doesn't align with user's need, or mentions a competitor)\n",
+    "The process for building your research data inventory using the OpenAI web search tool is as follows:\n",
     "\n",
-    "prerequisite pip install nest_asyncio"
+    "1. Obtain the search results (e.g., top 10 relevant pages) for each search term.\n",
+    "2. Extract and summarize the key points from each result.\n",
+    "3. Optionally, apply output guardrails to filter out irrelevant or undesirable results (for example, based on publication date, source, or content).\n",
+    "#\n",
+    "If you choose to implement your own custom search or browser-based retrieval, you may need additional setup such as API keys or environment configuration."
    ]
   },
   {
@@ -374,7 +376,7 @@
     "# ------------------------------------------------------------------\n",
     "# 2. Draft the report\n",
     "# ------------------------------------------------------------------\n",
-    "outline = \"\"\" Draft a comprehensive research report analyzing the latest trends in artificial intelligence (AI) developments within the healthcare industry over the past five years. The report should evaluate advancements in machine learning, deep learning, natural language processing, medical imaging, and other relevant AI applications, while also examining regulatory, ethical, and operational impacts on healthcare delivery. Include detailed case studies, emerging research areas, and recommendations for future innovation in the industry.\"\"\"  # ← customise as needed\n",
+    "outline = \"\"\" Draft a comprehensive research report analyzing the latest trends in artificial intelligence (AI) developments within the healthcare industry over the past five years. The report should evaluate advancements in machine learning, deep learning, natural language processing, medical imaging, and other relevant AI applications, while also examining regulatory, ethical, and operational impacts on healthcare delivery. Include detailed case studies, emerging research areas, and recommendations for future innovation in the industry.\"\"\"  # ← customize as needed\n",
     "\n",
     "report_agent = ReportWritingAgent(research_resources=research_results)\n",
     "\n",
@@ -502,18 +504,6 @@
     "        file.write(new_content)"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "2a890c80",
-   "metadata": {},
-   "source": []
-  },
-  {
-   "cell_type": "markdown",
-   "id": "255e0a06",
-   "metadata": {},
-   "source": []
-  },
   {
    "cell_type": "markdown",
    "id": "fb69c797",
@@ -522,7 +512,7 @@
     "### 5 — Guardrails & Best Practices <a id='best-practices'></a>\n",
     "* **Crawl → Walk → Run**: start with a single agent, then expand into a swarm. \n",
     "* **Expose intermediate reasoning** (“show the math”) to build user trust.  \n",
-    "* **Parameterise UX** so analysts can tweak report format and source mix. \n",
+    "* **Parameterize UX** so analysts can tweak report format and source mix. \n",
     "* **Native OpenAI tools first** (web browsing, file ingestion) before reinventing low‑level retrieval. "
    ]
   },