|
9 | 9 | "\n", |
10 | 10 | "## Introduction\n", |
11 | 11 | "\n", |
12 | | - "*This guide is intended for readers already familiar with OpenAI models and building LLM agents.*\n", |
| 12 | + "*This guide is for readers already familiar with OpenAI models and LLM agents, and want to see how to orchestrate a team of agents for a real-world, complex task.*\n", |
13 | 13 | "\n", |
14 | | - "Building a complex, multistep AI system often benefits from **multiple agents working in tandem**. This guide demonstrates how to orchestrate a team of agents using the OpenAI Agents SDK, through the example of a **portfolio research workflow**. Here, specialized agents (Macro, Fundamental, Quantitative) collaborate under a Portfolio Manager agent to solve a challenging investment analysis problem. We focus on high-level architecture, tool usage, and best practices for multi-agent collaboration, with all code and assets drawn from this repo.\n", |
| 14 | + "**What You'll Learn**\n", |
15 | 15 | "\n", |
16 | | - "By the end of this guide, you'll understand how to design a multi-agent system, choose collaboration patterns, configure various tool types for each agent, and run the system with tracing for observability.\n", |
| 16 | + "In this notebook, you'll learn how to use the OpenAI Agents SDK to design and implement a complex multi-agent collaboration system. Specifically, you'll see how to:\n", |
| 17 | + "- Build a workflow where multiple specialist agents (Macro, Fundamental, Quantitative) collaborate under a Portfolio Manager agent to solve a challenging investment research problem.\n", |
| 18 | + "- Use the \"agents as a tool\" approach, where a central agent orchestrates and calls other agents as tools for specific subtasks.\n", |
| 19 | + "- Leverage all major tool types supported by the SDK (custom Python functions, managed tools like Code Interpreter and WebSearch, and external MCP servers) in a single, integrated workflow.\n", |
| 20 | + "- Apply best practices for modularity, parallelism, and observability in agentic patterns.\n", |
| 21 | + "\n", |
| 22 | + "**Why this matters**\n", |
| 23 | + "\n", |
| 24 | + "The \"agents as a tool\" pattern is a powerful way to build transparent, auditable, and scalable multi-agent collaboration . This example demonstrates how to combine deep specialization, parallel execution, and robust orchestration using the OpenAI Agents SDK.\n", |
| 25 | + "\n", |
| 26 | + "By the end of this guide, you'll have a clear blueprint for building your own multi-agent workflows for research, analysis, or any complex task that benefits from expert collaboration.\n" |
| 27 | + ] |
| 28 | + }, |
| 29 | + { |
| 30 | + "cell_type": "markdown", |
| 31 | + "id": "ed547489", |
| 32 | + "metadata": {}, |
| 33 | + "source": [ |
17 | 34 | "\n", |
18 | 35 | "---\n", |
19 | 36 | "\n", |
|
29 | 46 | "8. [Breaking Down the Head Portfolio Manager Agent](#breaking-down-the-head-portfolio-manager-agent)\n", |
30 | 47 | "9. [Example Output](#example-output)\n", |
31 | 48 | "10. [Best Practices When Building Agents](#best-practices-when-building-agents)\n", |
32 | | - "11. [Further Reading & Best Practices](#further-reading--best-practices)\n", |
| 49 | + "11. [Further Reading & Best Practices](#further-reading--best-practices)\n" |
| 50 | + ] |
| 51 | + }, |
| 52 | + { |
| 53 | + "cell_type": "markdown", |
| 54 | + "id": "26670dad", |
| 55 | + "metadata": {}, |
| 56 | + "source": [ |
33 | 57 | "\n", |
34 | 58 | "---\n", |
35 | 59 | "\n", |
36 | 60 | "## What is Multi-Agent Collaboration?\n", |
37 | 61 | "\n", |
38 | | - "**Multi-agent collaboration** means multiple autonomous agents (LLM \"nodes\") coordinate to achieve an overarching goal that would be difficult for a single agent to handle. Instead of one monolithic prompt, each agent handles a specific subtask or expertise area, and an orchestration layer connects these agent \"nodes\" into a coherent workflow. This approach is useful for complex systems – for example, a financial analysis might be broken into macro-economic analysis, fundamental company analysis, and quantitative signal analysis, each handled by a different agent specialist. The agents share information and their results are combined to produce a final outcome.\n", |
| 62 | + "**Multi-agent collaboration** means multiple autonomous agents (LLM \"nodes\") coordinate to achieve an overarching goal that would be difficult for a single agent to handle. Instead of one monolithic prompt, each agent handles a specific subtask or expertise area, and an orchestration layer connects these agent \"nodes\" into a coherent workflow. This approach is useful for complex systems – for example, a financial analysis might be broken into macro-economic analysis, fundamental company analysis, and quantitative signal analysis, each handled by a different agent specialist. The agents share information and their results are combined to produce a final outcome.\n" |
| 63 | + ] |
| 64 | + }, |
| 65 | + { |
| 66 | + "cell_type": "markdown", |
| 67 | + "id": "4d5f3a58", |
| 68 | + "metadata": {}, |
| 69 | + "source": [ |
39 | 70 | "\n", |
40 | 71 | "### Collaboration Patterns: Handoff vs. Agent-as-Tool\n", |
41 | 72 | "\n", |
|
53 | 84 | "\n", |
54 | 85 | "Our system follows a **hub-and-spoke design**. The **Portfolio Manager agent** is the hub (central coordinator), and the **specialist agents** are the spokes. The user's query (e.g. \"How would a planned interest rate reduction affect my GOOGL holdings?\") goes first to the Portfolio Manager. The Portfolio Manager agent is prompted to break down the problem and delegate to the appropriate specialist agents. It treats each specialist as a callable tool, invoking them for their portion of the analysis. All three report back to the Portfolio Manager, which then synthesizes a final answer for the user.\n", |
55 | 86 | "\n", |
56 | | - "\n", |
| 87 | + "\n" |
| 88 | + ] |
| 89 | + }, |
| 90 | + { |
| 91 | + "cell_type": "markdown", |
| 92 | + "id": "a7a2ef1e", |
| 93 | + "metadata": {}, |
| 94 | + "source": [ |
57 | 95 | "\n", |
58 | 96 | "---\n", |
59 | 97 | "\n", |
|
345 | 383 | "id": "c74d9ac0", |
346 | 384 | "metadata": {}, |
347 | 385 | "source": [ |
| 386 | + "---\n", |
| 387 | + "\n", |
348 | 388 | "## Example Output\n", |
349 | 389 | "\n", |
350 | 390 | "Here's an example of an investment report generated through the workflow. See [`static/example_output/investment_report.md`](static/example_output/investment_report.md) for the full output, and the `static/example_output/` folder for referenced images and CSVs." |
351 | 391 | ] |
352 | 392 | }, |
353 | 393 | { |
354 | 394 | "cell_type": "code", |
355 | | - "execution_count": 1, |
| 395 | + "execution_count": null, |
356 | 396 | "id": "9fe6e452", |
357 | 397 | "metadata": {}, |
358 | | - "outputs": [ |
359 | | - { |
360 | | - "data": { |
361 | | - "text/markdown": [ |
362 | | - "# Investment Memo: Alphabet Inc. (GOOGL) – Impact of Planned Interest Rate Reduction (May 2025)\n", |
363 | | - "\n", |
364 | | - "## Executive Summary\n", |
365 | | - "\n", |
366 | | - "Alphabet Inc. (GOOGL) currently trades at \\$171.42 per share, with a market capitalization of \\$1.88 trillion and a P/E ratio of 16.91. The investment thesis is moderately constructive: while a planned interest rate reduction by the Federal Reserve is a mild tailwind, it is not the primary driver of GOOGL's price action. The most original, differentiated insight—fully aligned with our firm's vision—is that GOOGL's direct sensitivity to interest rates is modest (max weekly correlation with 10Y yield is ~0.29), and the real risk/reward hinges on the sustainability of AI-driven growth, sector rotation, and regulatory headwinds. This thesis is supported by robust technicals, strong fundamentals, and overwhelmingly positive analyst sentiment, but is tempered by the risk that AI optimism fades or macro/regulatory shocks emerge. The consensus view is justified by evidence: GOOGL's business remains resilient, but the variant view—where rate cuts fail to stimulate tech or sector rotation caps returns—should not be ignored. Key risks include regulatory action, macroeconomic uncertainty, and the potential for a shift in the AI narrative. In the best case, GOOGL could reach \\$200–\\$210 by year-end 2025; in the worst case, a retest of \\$160–\\$170 is plausible. This memo embodies the firm's vision by focusing on scenario planning, original quantitative analysis, and a critical assessment of consensus and variant views.\n", |
367 | | - "\n", |
368 | | - "## Fundamentals Perspective\n", |
369 | | - "\n", |
370 | | - "Alphabet's core business is driven by its dominance in digital advertising (Google Search, YouTube) and its growing cloud and AI segments. As of the latest quarter (Q1 2025), revenue was \\$90.2 billion, net income \\$34.5 billion, and EPS \\$2.81, with net margin at 38.3%. Margins have improved over the past year, and the company's scale and leadership in AI and cloud provide a durable moat. However, recent analyst price targets have been revised downward (Bernstein: \\$165, UBS: \\$209, Wolfe: \\$210), reflecting caution around regulatory and macroeconomic risks. The consensus view is justified: while Alphabet's financial strength and innovation are clear, regulatory scrutiny and macro headwinds (e.g., reduced ad budgets in downturns) are real risks. The most original insight is the company's ability to adapt and innovate, potentially mitigating some risks. The analysis is evidence-based, with recent quarterly data showing stable or improving margins:\n", |
371 | | - "\n", |
372 | | - "| Date | Revenue | Net Income | Gross Profit | Total Expenses | EPS | Net Margin (%) | Gross Margin (%) | Operating Margin (%) |\n", |
373 | | - "|:-----------|-----------:|-------------:|---------------:|-----------------:|------:|-----------------:|-------------------:|-----------------------:|\n", |
374 | | - "| 2025-03-31 | 9.0234e+10 | 3.454e+10 | 5.3873e+10 | 5.9628e+10 | 2.81 | 38.28 | 59.70 | 33.92 |\n", |
375 | | - "| 2024-12-31 | 9.6469e+10 | 2.6536e+10 | 5.5856e+10 | 6.5497e+10 | 2.15 | 27.51 | 57.90 | 32.11 |\n", |
376 | | - "| 2024-09-30 | 8.8268e+10 | 2.6301e+10 | 5.1794e+10 | 5.9747e+10 | 2.12 | 29.80 | 58.68 | 32.31 |\n", |
377 | | - "| 2024-06-30 | 8.4742e+10 | 2.3619e+10 | 4.9235e+10 | 5.7317e+10 | 1.89 | 27.87 | 58.10 | 32.36 |\n", |
378 | | - "| 2024-03-31 | 8.0539e+10 | 2.3662e+10 | 4.6827e+10 | 5.5067e+10 | 1.89 | 29.38 | 58.14 | 31.63 |\n", |
379 | | - "\n", |
380 | | - "Recent analyst sentiment is overwhelmingly positive, with 56 Buy, 12 Hold, and 0 Sell recommendations currently:\n", |
381 | | - "\n", |
382 | | - "| period | Buy | Hold | Sell |\n", |
383 | | - "|:-------------|------:|-------:|-------:|\n", |
384 | | - "| Current | 56 | 12 | 0 |\n", |
385 | | - "| 1 Month Ago | 55 | 12 | 0 |\n", |
386 | | - "| 2 Months Ago | 55 | 12 | 0 |\n", |
387 | | - "| 3 Months Ago | 53 | 12 | 0 |\n", |
388 | | - "\n", |
389 | | - "The fundamental view is aligned with the firm vision by focusing on evidence, scenario planning, and not simply following consensus. The main divergence from the firm vision would be if the analysis failed to consider the impact of regulatory or macro shocks, but this is addressed here.\n", |
390 | | - "\n", |
391 | | - "## Macro Perspective\n", |
392 | | - "\n", |
393 | | - "The macroeconomic environment is mixed. U.S. real GDP is expanding (\\$23.5 trillion, Q1 2025), unemployment is low (4.2%), and inflation remains elevated (CPI: 320.3). The Federal Reserve has kept rates at 4.25–4.50%, with a patient stance and a focus on evolving risks. The U.S. dollar is strong (DXY: 123.4), and recent tariffs have introduced uncertainty. Investors are rotating from U.S. tech to Asian equities, reflecting concerns about high valuations and better growth prospects abroad. The consensus macro view is that rate cuts will support tech valuations, but the variant view—supported by our firm's vision—is that sector rotation and trade policy could offset these benefits. Tail-risk scenarios include a base case where rate cuts support GOOGL (\\$180–\\$190 target), and a downside where trade tensions or sector rotation cap returns. The analysis is evidence-based, using FRED data and recent policy statements, and explicitly considers both best- and worst-case scenarios. The macro view is fully aligned with the firm vision by challenging consensus and planning for multiple outcomes.\n", |
394 | | - "\n", |
395 | | - "## Quantitative Perspective\n", |
396 | | - "\n", |
397 | | - "Quantitative analysis confirms that GOOGL's direct sensitivity to interest rates is modest. The mean weekly correlation with the 10Y Treasury yield is 0.29, and with the Fed Funds rate is 0.05, indicating that rate changes are not the primary driver of GOOGL's returns. Technicals are robust: GOOGL is above key moving averages, momentum is positive, and volatility is moderate. Scenario analysis shows that a rate cut is a mild tailwind, but if the move is already priced in or if technicals break down, a 5–10% pullback is possible. Analyst sentiment is strongly positive, and fundamentals (revenue, margins) are improving. Quantitative summary statistics:\n", |
398 | | - "\n", |
399 | | - "| Metric | Value |\n", |
400 | | - "|:----------------------------------------|----------:|\n", |
401 | | - "| Mean daily corr (FEDFUNDS, GOOGL) | 0.05 |\n", |
402 | | - "| Mean daily reg slope (FEDFUNDS, GOOGL) | 0.02 |\n", |
403 | | - "| Mean daily corr (DGS10, GOOGL) | 0.13 |\n", |
404 | | - "| Mean daily reg slope (DGS10, GOOGL) | 0.05 |\n", |
405 | | - "| Mean weekly corr (FEDFUNDS, GOOGL) | 0.05 |\n", |
406 | | - "| Mean weekly reg slope (FEDFUNDS, GOOGL) | 0.03 |\n", |
407 | | - "| Mean weekly corr (DGS10, GOOGL) | 0.29 |\n", |
408 | | - "| Mean weekly reg slope (DGS10, GOOGL) | 0.09 |\n", |
409 | | - "\n", |
410 | | - "Key charts and images:\n", |
411 | | - "\n", |
412 | | - "\n", |
413 | | - "\n", |
414 | | - "\n", |
415 | | - "\n", |
416 | | - "\n", |
417 | | - "\n", |
418 | | - "\n", |
419 | | - "\n", |
420 | | - "\n", |
421 | | - "\n", |
422 | | - "\n", |
423 | | - "\n", |
424 | | - "\n", |
425 | | - "\n", |
426 | | - "The quantitative view is original in its focus on scenario analysis and the modest rate sensitivity, and is aligned with the firm vision by not simply following consensus. Limitations include the short post-pandemic data window and the fact that GOOGL's price is driven by multiple factors (AI, ad market, regulation) beyond rates.\n", |
427 | | - "\n", |
428 | | - "## Portfolio Manager Perspective\n", |
429 | | - "\n", |
430 | | - "The PM synthesis is that all three specialist sections converge on a moderately constructive outlook, with a realistic year-end 2025 price target of \\$190–\\$210. The most original insight is that GOOGL's direct rate sensitivity is modest, and the real risk is whether AI-driven growth can continue or if sector rotation and regulatory headwinds will cap returns. The quant section is strong in highlighting robust technicals and sentiment, but also the risk of a \\$160–\\$170 retest in downside scenarios. The fundamental and macro sections emphasize the importance of monitoring regulatory and trade policy. If underweight large-cap tech, now is a reasonable entry point, but position sizing should reflect the risk of sector rotation or macro disappointment. The variant view—rate cuts failing to stimulate tech or a shift in AI narrative—should not be ignored. Position sizing and risk management are key, fully in line with the firm's vision of scenario planning and differentiated insight.\n", |
431 | | - "\n", |
432 | | - "## Recommendation & Answer to the Question\n", |
433 | | - "\n", |
434 | | - "The recommendation is to maintain or modestly increase exposure to GOOGL, especially if underweight large-cap tech, with a year-end 2025 price target of \\$200–\\$210 in the base case. This embodies the firm vision by focusing on original, evidence-based scenario analysis, not simply following consensus. The recommendation is justified by robust fundamentals, positive technicals, and strong analyst sentiment, but is tempered by the risk of sector rotation, regulatory action, or a shift in the AI narrative. If these risks materialize, a retest of \\$160–\\$170 is possible. Sizing and risk management should reflect these scenarios. This approach is differentiated, evidence-driven, and fully aligned with the firm's vision.\n", |
435 | | - "\n", |
436 | | - "**END_OF_MEMO**\n", |
437 | | - "\n", |
438 | | - "*DISCLAIMER: I am an AI language model, not a registered investment adviser. Information provided is educational and general in nature. Consult a qualified financial professional before making any investment decisions.*" |
439 | | - ], |
440 | | - "text/plain": [ |
441 | | - "<IPython.core.display.Markdown object>" |
442 | | - ] |
443 | | - }, |
444 | | - "metadata": {}, |
445 | | - "output_type": "display_data" |
446 | | - } |
447 | | - ], |
| 398 | + "outputs": [], |
448 | 399 | "source": [ |
449 | 400 | "# Render the actual investment report generated by the workflow\n", |
450 | 401 | "from pathlib import Path\n", |
|
0 commit comments