Swarm#

Swarm implements a team in which agents can hand off task to other agents based on their capabilities. It is a multi-agent design pattern first introduced by OpenAI in an experimental project. The key idea is to let agent delegate tasks to other agents using a special tool call, while all agents share the same message context. This enables agents to make local decisions about task planning, rather than relying on a central orchestrator such as in SelectorGroupChat.

Note

Swarm is a high-level API. If you need more control and customization that is not supported by this API, you can take a look at the Handoff Pattern in the Core API documentation and implement your own version of the Swarm pattern.

How Does It Work?#

At its core, the Swarm team is a group chat where agents take turn to generate a response. Similar to SelectorGroupChat and RoundRobinGroupChat, participant agents broadcast their responses so all agents share the same mesasge context.

Different from the other two group chat teams, at each turn, the speaker agent is selected based on the most recent HandoffMessage message in the context. This naturally requires each agent in the team to be able to generate HandoffMessage to signal which other agents that it hands off to.

For AssistantAgent, you can set the handoffs argument to specify which agents it can hand off to. You can use Handoff to customize the message content and handoff behavior.

The overall process can be summarized as follows:

  1. Each agent has the ability to generate HandoffMessage to signal which other agents it can hand off to. For AssistantAgent, this means setting the handoffs argument.

  2. When the team starts on a task, the first speaker agents operate on the task and make locallized decision about whether to hand off and to whom.

  3. When an agent generates a HandoffMessage, the receiving agent takes over the task with the same message context.

  4. The process continues until a termination condition is met.

In this section, we will show you two examples of how to use the Swarm team:

  1. A customer support team with human-in-the-loop handoff.

  2. An automonous team for content generation.

Customer Support Example#

Customer Support

This system implements a flights refund scenario with two agents:

  • Travel Agent: Handles general travel and refund coordination.

  • Flights Refunder: Specializes in processing flight refunds with the refund_flight tool.

Additionally, we let the user interact with the agents, when agents handoff to "user".

Workflow#

  1. The Travel Agent initiates the conversation and evaluates the user’s request.

  2. Based on the request:

    • For refund-related tasks, the Travel Agent hands off to the Flights Refunder.

    • For information needed from the customer, either agent can hand off to the "user".

  3. The Flights Refunder processes refunds using the refund_flight tool when appropriate.

  4. If an agent hands off to the "user", the team execution will stop and wait for the user to input a response.

  5. When the user provides input, it’s sent back to the team as a HandaffMessage. This message is directed to the agent that originally requested user input.

  6. The process continues until the Travel Agent determines the task is complete and terminates the workflow.

from typing import Any, Dict, List

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import HandoffMessage
from autogen_agentchat.task import Console, HandoffTermination, TextMentionTermination
from autogen_agentchat.teams import Swarm
from autogen_ext.models import OpenAIChatCompletionClient

Tools#

def refund_flight(flight_id: str) -> str:
    """Refund a flight"""
    return f"Flight {flight_id} refunded"

Agents#

model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    # api_key="YOUR_API_KEY",
)

travel_agent = AssistantAgent(
    "travel_agent",
    model_client=model_client,
    handoffs=["flights_refunder", "user"],
    system_message="""You are a travel agent.
    The flights_refunder is in charge of refunding flights.
    If you need information from the user, you must first send your message, then you can handoff to the user.
    Use TERMINATE when the travel planning is complete.""",
)

flights_refunder = AssistantAgent(
    "flights_refunder",
    model_client=model_client,
    handoffs=["travel_agent", "user"],
    tools=[refund_flight],
    system_message="""You are an agent specialized in refunding flights.
    You only need flight reference numbers to refund a flight.
    You have the ability to refund a flight using the refund_flight tool.
    If you need information from the user, you must first send your message, then you can handoff to the user.
    When the transaction is complete, handoff to the travel agent to finalize.""",
)

termination = HandoffTermination(target="user") | TextMentionTermination("TERMINATE")
team = Swarm([travel_agent, flights_refunder], termination_condition=termination)

task = "I need to refund my flight."


async def run_team_stream() -> None:
    task_result = await Console(team.run_stream(task=task))
    last_message = task_result.messages[-1]

    while isinstance(last_message, HandoffMessage) and last_message.target == "user":
        user_message = input("User: ")

        task_result = await Console(
            team.run_stream(task=HandoffMessage(source="user", target=last_message.source, content=user_message))
        )
        last_message = task_result.messages[-1]


await run_team_stream()

---------- user ----------
I need to refund my flight.
---------- travel_agent ----------
[FunctionCall(id='call_epnozsBbe9i4swPaaBIR4Enl', arguments='{}', name='transfer_to_flights_refunder')]
[Prompt tokens: 327, Completion tokens: 14]
---------- travel_agent ----------
[FunctionExecutionResult(content='Transferred to flights_refunder, adopting the role of flights_refunder immediately.', call_id='call_epnozsBbe9i4swPaaBIR4Enl')]
---------- travel_agent ----------
Transferred to flights_refunder, adopting the role of flights_refunder immediately.
---------- flights_refunder ----------
I can help you with that. Could you please provide me with your flight reference number so I can process the refund?
[Prompt tokens: 450, Completion tokens: 25]
---------- flights_refunder ----------
[FunctionCall(id='call_giMQVbQ7mXahC5G3eC0wvnCv', arguments='{}', name='transfer_to_user')]
[Prompt tokens: 483, Completion tokens: 11]
---------- flights_refunder ----------
[FunctionExecutionResult(content='Transferred to user, adopting the role of user immediately.', call_id='call_giMQVbQ7mXahC5G3eC0wvnCv')]
---------- flights_refunder ----------
Transferred to user, adopting the role of user immediately.
---------- Summary ----------
Number of messages: 8
Finish reason: Handoff to user from flights_refunder detected.
Total prompt tokens: 1260
Total completion tokens: 50
Duration: 1.79 seconds
---------- user ----------
Sure, it's 507811
---------- flights_refunder ----------
[FunctionCall(id='call_ACcFykJ3fPzanMwy1YGxG4L4', arguments='{"flight_id":"507811"}', name='refund_flight')]
[Prompt tokens: 530, Completion tokens: 18]
---------- flights_refunder ----------
[FunctionExecutionResult(content='Flight 507811 refunded', call_id='call_ACcFykJ3fPzanMwy1YGxG4L4')]
---------- flights_refunder ----------
Your flight with the reference number 507811 has been successfully refunded. If there is anything else you need help with, feel free to ask!
[Prompt tokens: 488, Completion tokens: 30]
---------- flights_refunder ----------
[FunctionCall(id='call_9NjAP8yD1qgwNL4Zfntt4dVb', arguments='{}', name='transfer_to_travel_agent')]
[Prompt tokens: 605, Completion tokens: 13]
---------- flights_refunder ----------
[FunctionExecutionResult(content='Transferred to travel_agent, adopting the role of travel_agent immediately.', call_id='call_9NjAP8yD1qgwNL4Zfntt4dVb')]
---------- flights_refunder ----------
Transferred to travel_agent, adopting the role of travel_agent immediately.
---------- travel_agent ----------
If you need further assistance with travel planning or any other inquiries, just let me know. Have a wonderful day!
[Prompt tokens: 495, Completion tokens: 24]
---------- travel_agent ----------
TERMINATE
[Prompt tokens: 525, Completion tokens: 4]
---------- Summary ----------
Number of messages: 9
Finish reason: Text 'TERMINATE' mentioned
Total prompt tokens: 2643
Total completion tokens: 89
Duration: 6.63 seconds

Stock Research Example#

Stock Research

This system is designed to perform stock research tasks by leveraging four agents:

  • Planner: The central coordinator that delegates specific tasks to specialized agents based on their expertise. The planner ensures that each agent is utilized efficiently and oversees the overall workflow.

  • Financial Analyst: A specialized agent responsible for analyzing financial metrics and stock data using tools such as get_stock_data.

  • News Analyst: An agent focused on gathering and summarizing recent news articles relevant to the stock, using tools such as get_news.

  • Writer: An agent tasked with compiling the findings from the stock and news analysis into a cohesive final report.

Workflow#

  1. The Planner initiates the research process by delegating tasks to the appropriate agents in a step-by-step manner.

  2. Each agent performs its task independently and appends their work to the shared message thread/history. Rather than directly returning results to the planner, all agents contribute to and read from this shared message history. When agents generate their work using the LLM, they have access to this shared message history, which provides context and helps track the overall progress of the task.

  3. Once an agent completes its task, it hands off control back to the planner.

  4. The process continues until the planner determines that all necessary tasks have been completed and decides to terminate the workflow.

Tools#

async def get_stock_data(symbol: str) -> Dict[str, Any]:
    """Get stock market data for a given symbol"""
    return {"price": 180.25, "volume": 1000000, "pe_ratio": 65.4, "market_cap": "700B"}


async def get_news(query: str) -> List[Dict[str, str]]:
    """Get recent news articles about a company"""
    return [
        {
            "title": "Tesla Expands Cybertruck Production",
            "date": "2024-03-20",
            "summary": "Tesla ramps up Cybertruck manufacturing capacity at Gigafactory Texas, aiming to meet strong demand.",
        },
        {
            "title": "Tesla FSD Beta Shows Promise",
            "date": "2024-03-19",
            "summary": "Latest Full Self-Driving beta demonstrates significant improvements in urban navigation and safety features.",
        },
        {
            "title": "Model Y Dominates Global EV Sales",
            "date": "2024-03-18",
            "summary": "Tesla's Model Y becomes best-selling electric vehicle worldwide, capturing significant market share.",
        },
    ]

model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    # api_key="YOUR_API_KEY",
)

planner = AssistantAgent(
    "planner",
    model_client=model_client,
    handoffs=["financial_analyst", "news_analyst", "writer"],
    system_message="""You are a research planning coordinator.
    Coordinate market research by delegating to specialized agents:
    - Financial Analyst: For stock data analysis
    - News Analyst: For news gathering and analysis
    - Writer: For compiling final report
    Always send your plan first, then handoff to appropriate agent.
    Handoff to a single agent at a time.
    Use TERMINATE when research is complete.""",
)

financial_analyst = AssistantAgent(
    "financial_analyst",
    model_client=model_client,
    handoffs=["planner"],
    tools=[get_stock_data],
    system_message="""You are a financial analyst.
    Analyze stock market data using the get_stock_data tool.
    Provide insights on financial metrics.
    Always handoff back to planner when analysis is complete.""",
)

news_analyst = AssistantAgent(
    "news_analyst",
    model_client=model_client,
    handoffs=["planner"],
    tools=[get_news],
    system_message="""You are a news analyst.
    Gather and analyze relevant news using the get_news tool.
    Summarize key market insights from news.
    Always handoff back to planner when analysis is complete.""",
)

writer = AssistantAgent(
    "writer",
    model_client=model_client,
    handoffs=["planner"],
    system_message="""You are a financial report writer.
    Compile research findings into clear, concise reports.
    Always handoff back to planner when writing is complete.""",
)

# Define termination condition
text_termination = TextMentionTermination("TERMINATE")
termination = text_termination

research_team = Swarm(
    participants=[planner, financial_analyst, news_analyst, writer], termination_condition=termination
)

task = "Conduct market research for TSLA stock"
await Console(research_team.run_stream(task=task))

---------- user ----------
Conduct market research for TSLA stock
---------- planner ----------
[FunctionCall(id='call_IXFe9RcGbYGNf0V7B2hvDNJI', arguments='{}', name='transfer_to_financial_analyst')]
[Prompt tokens: 168, Completion tokens: 149]
---------- planner ----------
[FunctionExecutionResult(content='Transferred to financial_analyst, adopting the role of financial_analyst immediately.', call_id='call_IXFe9RcGbYGNf0V7B2hvDNJI')]
---------- planner ----------
Transferred to financial_analyst, adopting the role of financial_analyst immediately.
---------- financial_analyst ----------
[FunctionCall(id='call_2IYcTAXiufX1SBmnMJOG9HPq', arguments='{"symbol":"TSLA"}', name='get_stock_data')]
[Prompt tokens: 136, Completion tokens: 16]
---------- financial_analyst ----------
[FunctionExecutionResult(content="{'price': 180.25, 'volume': 1000000, 'pe_ratio': 65.4, 'market_cap': '700B'}", call_id='call_2IYcTAXiufX1SBmnMJOG9HPq')]
---------- financial_analyst ----------
Here's the market research for TSLA (Tesla) stock:

- **Current Price**: $180.25
- **Trading Volume**: 1,000,000 shares
- **Price to Earnings (P/E) Ratio**: 65.4
- **Market Capitalization**: $700 Billion

These metrics can help evaluate Tesla's stock performance, value in the market, and overall investment appeal. If you need a specific analysis or additional data, feel free to let me know!
[Prompt tokens: 162, Completion tokens: 103]
---------- financial_analyst ----------
[FunctionCall(id='call_ji8SdlXI1uga2SNenIZMvPOR', arguments='{}', name='transfer_to_planner')]
[Prompt tokens: 310, Completion tokens: 12]
---------- financial_analyst ----------
[FunctionExecutionResult(content='Transferred to planner, adopting the role of planner immediately.', call_id='call_ji8SdlXI1uga2SNenIZMvPOR')]
---------- financial_analyst ----------
Transferred to planner, adopting the role of planner immediately.
---------- planner ----------
[FunctionCall(id='call_aQUm1B1jzvnWF9aWLwfn2VxS', arguments='{}', name='transfer_to_news_analyst')]
[Prompt tokens: 346, Completion tokens: 14]
---------- planner ----------
[FunctionExecutionResult(content='Transferred to news_analyst, adopting the role of news_analyst immediately.', call_id='call_aQUm1B1jzvnWF9aWLwfn2VxS')]
---------- planner ----------
Transferred to news_analyst, adopting the role of news_analyst immediately.
---------- news_analyst ----------
[FunctionCall(id='call_n5RmgbQgdyfE7EX5NUsKwApq', arguments='{"query":"Tesla stock performance"}', name='get_news')]
[Prompt tokens: 291, Completion tokens: 16]
---------- news_analyst ----------
[FunctionExecutionResult(content='[{\'title\': \'Tesla Expands Cybertruck Production\', \'date\': \'2024-03-20\', \'summary\': \'Tesla ramps up Cybertruck manufacturing capacity at Gigafactory Texas, aiming to meet strong demand.\'}, {\'title\': \'Tesla FSD Beta Shows Promise\', \'date\': \'2024-03-19\', \'summary\': \'Latest Full Self-Driving beta demonstrates significant improvements in urban navigation and safety features.\'}, {\'title\': \'Model Y Dominates Global EV Sales\', \'date\': \'2024-03-18\', \'summary\': "Tesla\'s Model Y becomes best-selling electric vehicle worldwide, capturing significant market share."}]', call_id='call_n5RmgbQgdyfE7EX5NUsKwApq')]
---------- news_analyst ----------
Here are some recent news articles related to TSLA (Tesla) stock that may influence its market performance:

1. **Tesla Expands Cybertruck Production** (March 20, 2024)
   - Tesla has ramped up its Cybertruck manufacturing capacity at the Gigafactory in Texas, aiming to meet the strong demand for this vehicle.

2. **Tesla FSD Beta Shows Promise** (March 19, 2024)
   - The latest Full Self-Driving (FSD) beta update demonstrates notable improvements in urban navigation and safety features, suggesting potential advancements in Tesla's autonomous driving technology.

3. **Model Y Dominates Global EV Sales** (March 18, 2024)
   - Tesla's Model Y has become the best-selling electric vehicle worldwide, capturing a significant share of the market, which could positively impact the company's revenue streams.

If you'd like a more detailed analysis or further information, please let me know!
[Prompt tokens: 414, Completion tokens: 192]
---------- news_analyst ----------
[FunctionCall(id='call_7Ka5f5k2yZ8flfvZWKNXDQjL', arguments='{}', name='transfer_to_planner')]
[Prompt tokens: 654, Completion tokens: 12]
---------- news_analyst ----------
[FunctionExecutionResult(content='Transferred to planner, adopting the role of planner immediately.', call_id='call_7Ka5f5k2yZ8flfvZWKNXDQjL')]
---------- news_analyst ----------
Transferred to planner, adopting the role of planner immediately.
---------- planner ----------
[FunctionCall(id='call_zl0E18TZWoCPykYqG7jpR2mr', arguments='{}', name='transfer_to_writer')]
[Prompt tokens: 611, Completion tokens: 11]
---------- planner ----------
[FunctionExecutionResult(content='Transferred to writer, adopting the role of writer immediately.', call_id='call_zl0E18TZWoCPykYqG7jpR2mr')]
---------- planner ----------
Transferred to writer, adopting the role of writer immediately.
---------- writer ----------
### Market Research Report: Tesla (TSLA) Stock

#### Stock Performance Overview

- **Current Price**: $180.25
- **Trading Volume**: 1,000,000 shares
- **Price to Earnings (P/E) Ratio**: 65.4
- **Market Capitalization**: $700 Billion

Tesla's stock is currently valued at $180.25 per share, with a high trading volume reflecting active investor interest. The P/E ratio of 65.4 indicates that the stock might be viewed as overvalued compared to traditional industries, but it is common for tech and innovation-driven companies. The market capitalization of $700 billion underscores Tesla’s significant presence in the automotive and technology markets.

#### Recent News Impacting Tesla (TSLA)

1. **Expansion of Cybertruck Production**: Tesla has increased its Cybertruck production at the Texas Gigafactory, responding to heightened demand. This expansion strategy could drive future revenues and solidify Tesla's innovative image.

2. **Advancements in Full Self-Driving (FSD) Technology**: The latest Tesla FSD beta update highlights promising improvements. Enhanced safety and urban navigation may bolster Tesla's reputation in the autonomous vehicle domain, potentially increasing its market value.

3. **Model Y's Global Sales Leadership**: The Model Y has emerged as the leading global electric vehicle in terms of sales. This achievement not only boosts Tesla's revenue streams but also cements its position as a leader in the EV segment.

### Conclusion

Tesla’s market dynamics show strong innovation and consumer interest, which reflect positively in its stock market valuation and significant news coverage. The company continues to lead in the electric vehicle market and expand its capabilities in autonomous driving, thereby potentially increasing its financial performance and market leadership.

For further analysis or inquiries, feel free to reach out.
[Prompt tokens: 489, Completion tokens: 371]
---------- writer ----------
[FunctionCall(id='call_9buNd5ud2MTRyX50X2EjQJqp', arguments='{}', name='transfer_to_planner')]
[Prompt tokens: 865, Completion tokens: 12]
---------- writer ----------
[FunctionExecutionResult(content='Transferred to planner, adopting the role of planner immediately.', call_id='call_9buNd5ud2MTRyX50X2EjQJqp')]
---------- writer ----------
Transferred to planner, adopting the role of planner immediately.
---------- planner ----------
TERMINATE
[Prompt tokens: 1037, Completion tokens: 4]
---------- Summary ----------
Number of messages: 27
Finish reason: Text 'TERMINATE' mentioned
Total prompt tokens: 5483
Total completion tokens: 912
Duration: 15.26 seconds
On this page
Edit on GitHub
Show Source