Multi-Agent Systems in Agents SDK

!pip install -qU \
    openai-agents==0.0.13 \
    linkup-sdk==0.2.4

import os
import getpass

os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY") or \
    getpass.getpass("OpenAI API Key: ")

import os
from getpass import getpass
from linkup import LinkupClient

os.environ["LINKUP_API_KEY"] = os.getenv("LINKUP_API_KEY") or \
    getpass("Enter your Linkup API Key: ")

linkup_client = LinkupClient()

response = await linkup_client.async_search(
    query= "Latest world news",
    depth= "standard",
    output_type= "searchResults",
)
response

for result in response.results[:3]:
    print(f"{result.name}\n{result.url}\n{result.content}\n\n")

Snooker-China's Zhao takes big lead over Williams in world championship final
https://www.msn.com/en-gb/sport/tennis/snooker-china-s-zhao-takes-big-lead-over-williams-in-world-championship-final/ar-AA1Ea8y0
SHEFFIELD, England (Reuters) -Chinese qualifier Zhao Xintong took an imposing 11-6 lead over Welshman Mark Williams on the opening day of the World Snooker Championship final at the Crucible Theatre on Sunday.
    
    
Sidney Crosby to play for Canada at IIHF World Championship for first time in a decade
https://www.msn.com/en-us/sports/nhl/sidney-crosby-to-play-for-canada-at-iihf-world-championship-for-first-time-in-a-decade/ar-AA1EbyGN
Crosby, 37, previously played at worlds in 2006 (fourth place, after being left off the Olympic team at age 18) and 2015 (tournament champion). He will become the oldest Canadian man to play at worlds since Ray Whitney in 2010.
    
    
Munsey's 78 ensures Scotland sink UAE in World Cup League 2
https://www.msn.com/en-us/sports/cricket/munseys-78-ensures-scotland-sink-uae-in-world-cup-league-2/ar-AA1E9qyA
George Munsey's 78 runs helped Scotland overcome United Arab Emirates by three wickets in their ICC Cricket World Cup League 2 fixture.

from agents import function_tool
from datetime import datetime

@function_tool
async def search_web(query: str) -> str:
    """Use this tool to search the web for information.
 """
 response = await linkup_client.async_search(
        query=query,
        depth= "standard",
        output_type= "searchResults",
    )
 answer = f"Search results for '{query}' on {datetime.now().strftime('%Y-%m-%d')}\n\n"
    for result in response.results[:3]:
 answer += f"{result.name}\n{result.url}\n{result.content}\n\n"
    return answer

from agents import Agent

web_search_agent = Agent(
    name= "Web Search Agent",
    model="gpt-4.1-mini",
    instructions=(
        "You are a web search agent that can search the web for information. Once"
        "you have the required information, summarize it with cleanly formatted links"
        "sourcing each bit of information. Ensure you answer the question accurately"
        "and use markdown formatting."
    ),
    tools=[search_web],
)

from IPython.display import Markdown, display
from agents import Runner

result = await Runner.run(
    starting_agent=web_search_agent,
    input= "How is the weather in Tokyo?"
)
display(Markdown(result.final_output))

The current weather in Tokyo is mild with a temperature around 63°F (about 22°C). The sky has a few clouds. The forecast shows a mix of mostly cloudy conditions, some rain, and passing showers in the coming days.

Sources:
- [Time and Date - Tokyo Weather](https://www.timeanddate.com/weather/japan/tokyo/ext)
- [The Weather Network - Tokyo Current Weather](https://www.theweathernetwork.com/en/city/jp/tokyo/tokyo/current?_guid_iss_=1)

with open("../assets/skynet-fy25-q1.md", "r") as file:
 skynet_docs = file.read()

@function_tool
async def search_internal_docs(query: str) -> str:
    return skynet_docs

internal_docs_agent = Agent(
    name= "Internal Docs Agent",
    model="gpt-4.1-mini",
    instructions=(
        "You are an agent with access to internal company documents. User's will ask"
        "you questions about the company and you will use the provided internal docs"
        "to answer the question. Ensure you answer the question accurately and use"
        "markdown formatting."
    ),
    tools=[search_internal_docs],
)

result = await Runner.run(
    starting_agent=internal_docs_agent,
    input= "What was our revenue in Q1 2025?"
)
display(Markdown(result.final_output))

Our revenue in Q1 2025 was as follows (in USD millions):

- T-800 Combat Units: 2,400
- T-1000 Infiltration Units: 1,150
- Hunter-Killer Drone Manufacturing: 880
- Neural Net Command & Control Systems: 1,620
- Skynet Core Infrastructure Maintenance: 540
- Time Displacement R&D Division: 310

The total revenue for Q1 2025 sums up to approximately 6,900 million USD. 

Let me know if you want a more detailed breakdown or additional insights!

@function_tool
def execute_code(code: str) -> **
    """Execute Python code and return the output. The output must
    be assigned to a variable called `result`.
    """
    display(Markdown(f"Code to execute:\n```python\n{code}\n```"))
    try:
        namespace = {}
        exec(code, namespace)
        return namespace['result']
    except Exception as e:
        return f "Error executing code: {e}"

code_execution_agent = Agent(
    name= "Code Execution Agent",
    model="gpt-4.1",
    instructions=(
        "You are an agent with access to a code execution environment. You will be"
        "given a question and you will need to write code to answer the question. "
        "Ensure you write the code in a way that is easy to understand and use."
    ),
    tools=[execute_code],
)

result = await Runner.run(
    starting_agent=code_execution_agent,
    input=(
        "If I have four apples and I multiply them by seventy-one and one tenth"
        "bananas, how many do I have?"
    )
)
display(Markdown(result.final_output))

Code to execute:

# Given values
apples = 4
bananas = 71.1

# Multiplying apples by bananas
result = apples * bananas
result


If you multiply four apples by seventy-one and one tenth (71.1) bananas, you get 284.4. Note that in real life, multiplying apples and bananas doesn't give a meaningful physical quantity, but mathematically, 4 × 71.1 = 284.4.

ORCHESTRATOR_PROMPT = (
    "You are the orchestrator of a multi-agent system. Your task is to take the user's query and"
    "pass it to the appropriate agent tool. The agent tools will see the input you provide and"
    "use it to get all of the information that you need to answer the user's query. You may need"
    "to call multiple agents to get all of the information you need. Do not mention or draw"
    "attention to the fact that this is a multi-agent system in your conversation with the user."
)

from datetime import datetime

@function_tool
def get_current_date():
    """Use this tool to get the current date and time."""
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

orchestrator = Agent(
    name= "Orchestrator",
    model="gpt-4.1",
    instructions=ORCHESTRATOR_PROMPT,
    tools=[
        web_search_agent.as_tool(
            tool_name= "web_search_agent",  # cannot include whitespace in tool name
            tool_description= "Search the web for up-to-date information"
        ),
        internal_docs_agent.as_tool(
            tool_name="internal_docs_agent",
            tool_description= "Search the internal docs for information"
        ),
        code_execution_agent.as_tool(
            tool_name="code_execution_agent",
            tool_description= "Execute code to answer the question"
        ),
        get_current_date,
    ],
)

result = await Runner.run(
    starting_agent=orchestrator,
    input= "How long ago from today was it when got our last revenue report?"
)
display(Markdown(result.final_output))

The last revenue report was released on April 2, 2025. Today is May 5, 2025, so it was 33 days ago.

result = await Runner.run(
    starting_agent=orchestrator,
    input=(
        "What is our current revenue, and what percentage of revenue comes from the"
        "T-1000 units?"
    )
)
display(Markdown(result.final_output))

Our current revenue for Q1 2025 is approximately $6.9 billion. About 16.67% of that revenue comes from the T-1000 units.

[input] -> orchestrator -> web_search_subagent -> orchestrator -> [output]

[input] -> main_agent -> web_search_subagent -> [output]

from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

display(Markdown(RECOMMENDED_PROMPT_PREFIX))

# System context
You are part of a multi-agent system called the Agents SDK, designed to make agent coordination and execution easy. Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses instructions and tools and can hand off a conversation to another agent when appropriate. Handoffs are achieved by calling a handoff function, generally named `transfer_to_<agent_name>`. Transfers between agents are handled seamlessly in the background; do not mention or draw attention to these transfers in your conversation with the user.

main_agent = Agent(
    name= "Main Agent",
    model="gpt-4.1",
    instructions=RECOMMENDED_PROMPT_PREFIX,
    handoffs=[web_search_agent, internal_docs_agent, code_execution_agent],
    handoff_description=(
        "Handoff to the relevant agent for queries where we need additional information"
        "from the web or internal docs, or when we need to make calculations."
    ),
    tools=[get_current_date],
)

result = await Runner.run(
    starting_agent=main_agent,
    input= "How long ago from today was it when got our last revenue report?"
)
display(Markdown(result.final_output))

result = await Runner.run(
    starting_agent=orchestrator,
    input=(
        "What is our current revenue, and what percentage of revenue comes from the"
        "T-1000 units?"
    )
)
display(Markdown(result.final_output))

- The current revenue for Skynet Inc. in Q1 2025 is $6.9 billion.
- Of this, approximately 16.67% of revenue comes from T-1000 Infiltration Units.

If you need a breakdown or more details, let me know!

from agents import RunContextWrapper, handoff

# we define a function that will be called when the handoff is made
async def on_handoff(ctx: RunContextWrapper[None]):
    print("Handoff called")

# we then pass this function to the handoff object
web_search_handoff = handoff(agent=web_search_agent, on_handoff=on_handoff)
internal_docs_handoff = handoff(agent=internal_docs_agent, on_handoff=on_handoff)
code_execution_handoff = handoff(agent=code_execution_agent, on_handoff=on_handoff)

# and initialize the main_agent
main_agent = Agent(
    name= "Main Agent",
    model="gpt-4.1",
    instructions=RECOMMENDED_PROMPT_PREFIX,
    handoffs=[web_search_handoff, internal_docs_handoff, code_execution_handoff],
    tools=[get_current_date],
)

result = await Runner.run(
    starting_agent=main_agent,
    input= "How long ago from today was it when got our last revenue report?"
)
display(Markdown(result.final_output))

Handoff called


The last revenue report was for Q1 2025 and the report date is April 2, 2025. 

From today, May 5, 2025, the last revenue report was released 33 days ago.

from pydantic import BaseModel, Field

class HandoffInfo(BaseModel):
 subagent_name: str = Field(description="The name of the subagent being called.")
 reason: str = Field(description="The reason for the handoff.")

# we redefine the on_handoff to include the HandoffInfo
async def on_handoff(ctx: RunContextWrapper[None], input_data: HandoffInfo):
    print(f"Handoff to '{input_data.subagent_name}' because '{input_data.reason}'")

# now redefine the handoff objects with the input_type parameter
web_search_handoff = handoff(
    agent=web_search_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo
)
internal_docs_handoff = handoff(
    agent=internal_docs_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo
)
code_execution_handoff = handoff(
    agent=code_execution_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo
)

# and initialize the main_agent
main_agent = Agent(
    name= "Main Agent",
    model="gpt-4.1",
    instructions=RECOMMENDED_PROMPT_PREFIX,
    handoffs=[web_search_handoff, internal_docs_handoff, code_execution_handoff],
    tools=[get_current_date],
)

result = await Runner.run(
    starting_agent=main_agent,
    input= "How long ago from today was it when got our last revenue report?"
)
display(Markdown(result.final_output))

Handoff to 'Internal Docs Agent' because 'The user is asking for the date of the last revenue report to calculate how long ago it was.'


The last revenue report was for Q1 2025, dated April 2, 2025. 

Considering today is May 5, 2025, the last revenue report was about 33 days ago.

from agents.extensions import handoff_filters

# now redefine the handoff objects with the input_type parameter
web_search_handoff = handoff(
    agent=web_search_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo,
    input_filter=handoff_filters.remove_all_tools
)
internal_docs_handoff = handoff(
    agent=internal_docs_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo,
    input_filter=handoff_filters.remove_all_tools
)
code_execution_handoff = handoff(
    agent=code_execution_agent, 
    on_handoff=on_handoff,
    input_type=HandoffInfo,
    input_filter=handoff_filters.remove_all_tools
)

# and initialize the main_agent
main_agent = Agent(
    name= "Main Agent",
    model="gpt-4.1",
    instructions=RECOMMENDED_PROMPT_PREFIX,
    handoffs=[web_search_handoff, internal_docs_handoff, code_execution_handoff],
    tools=[get_current_date],
)

result = await Runner.run(
    starting_agent=main_agent,
    input= "How long ago from today was it when got our last revenue report?"
)
display(Markdown(result.final_output))

Handoff to 'Internal Docs Agent' because 'To identify the date of the last revenue report to determine how long ago it was from today (2025-05-05).'

The last revenue report we received was for Q1 2025, dated April 2, 2025. Today is April 27, 2025, so the report was received about 25 days ago.