Skip to content

Commit 8b1d2fa

Browse files
msingh-openaimsingh-openai
committed
Initial draft
1 parent ab40061 commit 8b1d2fa

File tree

1 file changed

+352
-0
lines changed

1 file changed

+352
-0
lines changed

‎examples/agents_sdk/AI_Research_Assistant_Cookbook.ipynb

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,352 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "85b66af9",
6+
"metadata": {},
7+
"source": [
8+
"# Building an **AI Research Assistant** with the OpenAI Agents SDK\n",
9+
"\n",
10+
"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",
11+
"\n",
12+
"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",
13+
"\n",
14+
"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. "
15+
]
16+
},
17+
{
18+
"cell_type": "markdown",
19+
"id": "0dcd3942",
20+
"metadata": {},
21+
"source": [
22+
"## Table of Contents\n",
23+
"1. [Overview](#overview)\n",
24+
"2. [Solution Workflow](#workflow)\n",
25+
"3. [High‑Level Architecture](#architecture)\n",
26+
"4. [Agent Definitions (Pseudo Code)](#agents)\n",
27+
" * Research Planning Agent\n",
28+
" * Web Search Agent\n",
29+
" * Knowledge Assistant Agent\n",
30+
" * Report Creation Agent\n",
31+
" * Data Analysis Agent (optional)\n",
32+
" * Image‑Gen Agent (optional)\n",
33+
"5. [Guardrails & Best Practices](#best-practices)\n",
34+
"6. [Risks & Mitigation](#risks)"
35+
]
36+
},
37+
{
38+
"cell_type": "markdown",
39+
"id": "a32e358e",
40+
"metadata": {},
41+
"source": [
42+
"### 1 — Overview <a id='overview'></a>\n",
43+
"The AI Research Assistant helps drives better research quality and faster turnaround for knowledge content.\n",
44+
"\n",
45+
"1. **Performs autonomous Internet research** to gather the most recent sources.\n",
46+
"2. **Incorporates internal data sources** such as a Company's proprietery knowledge sources. \n",
47+
"3. **Reduces analyst effort from days to minutes** by automating search, curation and first‑draft writing.\n",
48+
"4. **Produces draft reports with citations** and built‑in hallucination detection."
49+
]
50+
},
51+
{
52+
"cell_type": "markdown",
53+
"id": "33cb6ce3",
54+
"metadata": {},
55+
"source": [
56+
"### 2 — Solution Workflow <a id='workflow'></a>\n",
57+
"The typical workflow consists of five orchestrated steps: \n",
58+
"\n",
59+
"| Step | Purpose | Model |\n",
60+
"|------|---------|-------|\n",
61+
"| **Query Expansion** | Draft multi‑facet prompts / hypotheses | `gpt‑4o` |\n",
62+
"| **Search‑Term Generation** | Expand/clean user query into rich keyword list | `gpt‑4o` |\n",
63+
"| **Conduct Research** | Run web & internal searches, rank & summarise results | `gpt‑4o` + tools |\n",
64+
"| **Draft Report** | Produce first narrative with reasoning & inline citations | `o1` / `gpt‑4o` |\n",
65+
"| **Report Expansion** | Polish formatting, add charts / images / appendix | `gpt‑4o` + tools |"
66+
]
67+
},
68+
{
69+
"cell_type": "markdown",
70+
"id": "dcb4e6dc",
71+
"metadata": {},
72+
"source": [
73+
"### 3 — High‑Level Architecture <a id='architecture'></a>\n",
74+
"The following diagram groups agents and tools:\n",
75+
"\n",
76+
"* **Research Planning Agent** – interprets the user request and produces a research plan/agenda.\n",
77+
"* **Knowledge Assistant Agent** – orchestrates parallel web & file searches via built‑in tools, curates short‑term memory.\n",
78+
"* **Web Search Agent(s)** – perform Internet queries, deduplicate, rank and summarise pages.\n",
79+
"* **Report Creation Agent** – consumes curated corpus and drafts the structured report.\n",
80+
"* **(Optional) Data Analysis Agent** – executes code for numeric/CSV analyses via the Code Interpreter tool.\n",
81+
"* **(Optional) Image‑Gen Agent** – generates illustrative figures.\n",
82+
"\n",
83+
"Input/output guardrails wrap user prompts and final content for policy, safety and citation checks."
84+
]
85+
},
86+
{
87+
"cell_type": "markdown",
88+
"id": "d3464739",
89+
"metadata": {},
90+
"source": [
91+
"### 4 — Pre-requisites <a id='pre-requisites'></a>\n",
92+
"\n",
93+
"Create a virual environment \n",
94+
"\n",
95+
"Install dependencies "
96+
]
97+
},
98+
{
99+
"cell_type": "code",
100+
"execution_count": 1,
101+
"id": "3a16ac1f",
102+
"metadata": {},
103+
"outputs": [
104+
{
105+
"name": "stdout",
106+
"output_type": "stream",
107+
"text": [
108+
"Note: you may need to restart the kernel to use updated packages.\n"
109+
]
110+
}
111+
],
112+
"source": [
113+
"%pip install openai openai-agents --quiet"
114+
]
115+
},
116+
{
117+
"cell_type": "markdown",
118+
"id": "69135215",
119+
"metadata": {},
120+
"source": [
121+
"### 5 — Agents (Pseudo Code) <a id='agents'></a>\n",
122+
"Below are skeletal class definitions illustrating how each agent’s policy and tool‑usage might look."
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"id": "b9f3062e",
128+
"metadata": {},
129+
"source": [
130+
"#### Step 1 - Query Expansion"
131+
]
132+
},
133+
{
134+
"cell_type": "code",
135+
"execution_count": null,
136+
"id": "b576089c",
137+
"metadata": {},
138+
"outputs": [
139+
{
140+
"name": "stdout",
141+
"output_type": "stream",
142+
"text": [
143+
"Draft a comprehensive research report analyzing the evolution and impact of artificial intelligence (AI) over the past five years. This report should investigate key trends that have emerged during this period, including advancements in machine learning models like GPT and BERT, the rise of AI in industries such as healthcare, finance, and autonomous vehicles, and the ethical considerations surrounding AI development and implementation. Delve into how these trends have influenced technological growth, business strategies, and regulatory measures globally. Evaluate the societal and economic implications of these advancements and provide insights into future directions AI might take. Use a variety of sources, including scholarly articles, industry reports, and expert interviews, to support your analysis and conclusions.\n"
144+
]
145+
}
146+
],
147+
"source": [
148+
"from agents import Agent, Runner\n",
149+
"\n",
150+
"query_expansion_agent = Agent(\n",
151+
" name=\"Query Expansion Agent\",\n",
152+
" instructions=\"\"\"You are a helpful agent who is given a research prompt from the user as input. \n",
153+
" Your task is to expand the prompt into a more complete and actionable research prompt. Do not write the research \n",
154+
" paper, just improve the prompt in about one paragraph. Only respond with the expanded prompt no qualifiers.\"\"\",\n",
155+
" tools=[],\n",
156+
" model=\"gpt-4o\", \n",
157+
")\n",
158+
"\n",
159+
"result = await Runner.run(query_expansion_agent, \"Draft a research report on latest trends in persona auto insurance in the US\")\n",
160+
"\n",
161+
"expanded_prompt = result.final_output \n",
162+
"\n",
163+
"print(expanded_prompt)"
164+
]
165+
},
166+
{
167+
"cell_type": "markdown",
168+
"id": "6b1b10e7",
169+
"metadata": {},
170+
"source": [
171+
"#### Step 2 - Web Search Terms "
172+
]
173+
},
174+
{
175+
"cell_type": "markdown",
176+
"id": "725969cb",
177+
"metadata": {},
178+
"source": [
179+
"Generate the web search terms. You can customize the number of search terms generated to a give level of depth. "
180+
]
181+
},
182+
{
183+
"cell_type": "code",
184+
"execution_count": 13,
185+
"id": "d3b4d4af",
186+
"metadata": {},
187+
"outputs": [
188+
{
189+
"name": "stdout",
190+
"output_type": "stream",
191+
"text": [
192+
"Search_Queries=['Evolution of AI technology 2020-2025', 'Impact of machine learning models GPT and BERT on industries', 'AI advancements in healthcare and finance 2025', 'Ethics and AI development 2025', 'Future directions for artificial intelligence in various sectors']\n",
193+
"(0, 'Evolution of AI technology 2020-2025')\n",
194+
"(1, 'Impact of machine learning models GPT and BERT on industries')\n",
195+
"(2, 'AI advancements in healthcare and finance 2025')\n",
196+
"(3, 'Ethics and AI development 2025')\n",
197+
"(4, 'Future directions for artificial intelligence in various sectors')\n"
198+
]
199+
}
200+
],
201+
"source": [
202+
"from pydantic import BaseModel\n",
203+
"\n",
204+
"class SearchTerms(BaseModel):\n",
205+
" \"\"\"Structured output model for search-terms suggestions.\"\"\"\n",
206+
" Search_Queries: list[str]\n",
207+
"\n",
208+
"\n",
209+
"search_terms_agent = Agent(\n",
210+
" name=\"Search Terms Agent\",\n",
211+
" instructions=\"\"\"You are a helpful agent assigned a research task. Your job is to provide the top \n",
212+
" 5 Search Queries relevant to the given topic in this year (2025). The output should be in JSON format.\n",
213+
"\n",
214+
" Example format provided below:\n",
215+
" <START OF EXAMPLE>\n",
216+
" {\n",
217+
" \"Search_Queries\": [\n",
218+
" \"Top ranked auto insurance companies US 2025 by market capitalization\",\n",
219+
" \"Geico rates and comparison with other auto insurance companies\",\n",
220+
" \"Insurance premiums of top ranked companies in the US in 2025\", \n",
221+
" \"Total cost of insuring autos in US 2025\", \n",
222+
" \"Top customer service feedback for auto insurance in 2025\"\n",
223+
" ]\n",
224+
" }\n",
225+
" </END OF EXAMPLE>\n",
226+
" \"\"\",\n",
227+
" tools=[],\n",
228+
" model=\"gpt-4o\", \n",
229+
" output_type=SearchTerms,\n",
230+
")\n",
231+
"\n",
232+
"result = await Runner.run(search_terms_agent, expanded_prompt)\n",
233+
"\n",
234+
"search_terms_raw = result.final_output\n",
235+
"\n",
236+
"print(search_terms_raw)\n",
237+
"\n",
238+
"\n",
239+
"for query in enumerate(search_terms_raw.Search_Queries):\n",
240+
" print(f\"{query}\")"
241+
]
242+
},
243+
{
244+
"cell_type": "code",
245+
"execution_count": null,
246+
"id": "a477b6a8",
247+
"metadata": {},
248+
"outputs": [],
249+
"source": [
250+
"class KnowledgeAssistantAgent:\n",
251+
" \"\"\"Curates short‑term memory of research snippets.\"\"\"\n",
252+
" def run(self, web_snippets, file_snippets):\n",
253+
" corpus = web_snippets + file_snippets\n",
254+
" # Vector‑embed & cluster (pseudo)\n",
255+
" # ...\n",
256+
" # Return pruned, deduplicated corpus\n",
257+
" return corpus[:50] # top‑N"
258+
]
259+
},
260+
{
261+
"cell_type": "code",
262+
"execution_count": null,
263+
"id": "de168943",
264+
"metadata": {},
265+
"outputs": [],
266+
"source": [
267+
"class ReportCreationAgent:\n",
268+
" \"\"\"Drafts the first complete report with citations.\"\"\"\n",
269+
" def run(self, curated_corpus, outline):\n",
270+
" report = client.chat(\n",
271+
" model='gpt-4o',\n",
272+
" system_prompt='Write a research report following the outline. Cite sources in IEEE style.',\n",
273+
" user_prompt=str({'outline': outline, 'corpus': curated_corpus}),\n",
274+
" )\n",
275+
" return report.text"
276+
]
277+
},
278+
{
279+
"cell_type": "code",
280+
"execution_count": null,
281+
"id": "40c6bbca",
282+
"metadata": {},
283+
"outputs": [],
284+
"source": [
285+
"# --- Orchestration skeleton ---\n",
286+
"def generate_research_paper(topic: str):\n",
287+
" plan = ResearchPlanningAgent().run(topic)\n",
288+
"\n",
289+
" web_results = WebSearchAgent().run(plan['search_terms'])\n",
290+
" # TODO: file_results via file_search if internal corpus available\n",
291+
" file_results = []\n",
292+
"\n",
293+
" curated = KnowledgeAssistantAgent().run(web_results, file_results)\n",
294+
" draft = ReportCreationAgent().run(curated, plan['outline'])\n",
295+
" return draft\n"
296+
]
297+
},
298+
{
299+
"cell_type": "markdown",
300+
"id": "fb69c797",
301+
"metadata": {},
302+
"source": [
303+
"### 5 — Guardrails & Best Practices <a id='best-practices'></a>\n",
304+
"* **Crawl → Walk → Run**: start with a single agent, then expand into a swarm. \n",
305+
"* **Expose intermediate reasoning** (“show the math”) to build user trust. \n",
306+
"* **Parameterise UX** so analysts can tweak report format and source mix. \n",
307+
"* **Native OpenAI tools first** (web browsing, file ingestion) before reinventing low‑level retrieval. "
308+
]
309+
},
310+
{
311+
"cell_type": "markdown",
312+
"id": "1bdcab82",
313+
"metadata": {},
314+
"source": [
315+
"### 6 — Risks & Mitigation <a id='risks'></a>\n",
316+
"| Pitfall | Mitigation |\n",
317+
"|---------|------------|\n",
318+
"| Scope‑creep & endless roadmap | Narrow MVP & SMART milestones | fileciteturn1file4L23-L24 |\n",
319+
"| Hallucinations & weak guardrails | Golden‑set evals, RAG with citation checks | fileciteturn1file4L25-L26 |\n",
320+
"| Run‑away infra costs | Cost curve modelling; efficient models + autoscaling | fileciteturn1file4L27-L28 |\n",
321+
"| Talent gaps | Upskill & leverage Agents SDK to offload core reasoning | fileciteturn1file4L29-L30 |"
322+
]
323+
},
324+
{
325+
"cell_type": "markdown",
326+
"id": "5b40dcf3",
327+
"metadata": {},
328+
"source": []
329+
}
330+
],
331+
"metadata": {
332+
"kernelspec": {
333+
"display_name": ".venv",
334+
"language": "python",
335+
"name": "python3"
336+
},
337+
"language_info": {
338+
"codemirror_mode": {
339+
"name": "ipython",
340+
"version": 3
341+
},
342+
"file_extension": ".py",
343+
"mimetype": "text/x-python",
344+
"name": "python",
345+
"nbconvert_exporter": "python",
346+
"pygments_lexer": "ipython3",
347+
"version": "3.13.1"
348+
}
349+
},
350+
"nbformat": 4,
351+
"nbformat_minor": 5
352+
}

0 commit comments

Comments
 (0)