From 3748dffd8c9eb70405f74f08aa849d71052f86a6 Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Mon, 28 Jul 2025 14:20:30 -0700 Subject: [PATCH] debate multi agent orchestration docs --- .../orchestration_examples/LICENSE => LICENSE | 0 docs/mkdocs.yml | 2 +- docs/swarms/structs/orchestration_methods.md | 549 ++++++++++++++++++ 3 files changed, 550 insertions(+), 1 deletion(-) rename examples/multi_agent/orchestration_examples/LICENSE => LICENSE (100%) create mode 100644 docs/swarms/structs/orchestration_methods.md diff --git a/examples/multi_agent/orchestration_examples/LICENSE b/LICENSE similarity index 100% rename from examples/multi_agent/orchestration_examples/LICENSE rename to LICENSE diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e92cf446..ea111fc9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -276,7 +276,7 @@ nav: - Documentation: - Overview: "swarms/structs/overview.md" - Custom Multi Agent Architectures: "swarms/structs/custom_swarm.md" - + - Debate Multi-Agent Architectures: "swarms/structs/orchestration_methods.md" - MajorityVoting: "swarms/structs/majorityvoting.md" - RoundRobin: "swarms/structs/round_robin_swarm.md" diff --git a/docs/swarms/structs/orchestration_methods.md b/docs/swarms/structs/orchestration_methods.md new file mode 100644 index 00000000..d4f53584 --- /dev/null +++ b/docs/swarms/structs/orchestration_methods.md @@ -0,0 +1,549 @@ +# Multi-Agent Orchestration Methods + +Swarms provides a comprehensive suite of orchestration methods for coordinating multiple AI agents in structured conversations and decision-making processes. These methods enable sophisticated multi-agent interactions like debates, panel discussions, negotiations, and more. + +## Overview + +The orchestration methods provide structured frameworks for: +- Turn-based debates between two agents +- Expert panel discussions with a moderator +- Round table discussions with multiple participants +- Structured interviews with follow-up questions +- Academic peer review processes +- Mediation sessions for conflict resolution +- Brainstorming sessions for idea generation +- Trial simulations with legal roles +- Council meetings with voting procedures +- Mentorship sessions with feedback loops +- Complex negotiations between parties + +## Methods Overview + +| Method | Description | Use Case | +|--------|-------------|----------| +| OneOnOneDebate | Turn-based debate between two agents | Philosophical discussions, arguments | +| ExpertPanelDiscussion | Moderated panel with multiple experts | Professional discussions, expert opinions | +| RoundTableDiscussion | Facilitated round table with participants | Group discussions, brainstorming | +| InterviewSeries | Structured interview with follow-ups | Q&A sessions, information gathering | +| PeerReviewProcess | Academic peer review simulation | Research review, feedback processes | +| MediationSession | Conflict resolution mediation | Dispute resolution, negotiations | +| BrainstormingSession | Creative idea generation session | Innovation, problem solving | +| TrialSimulation | Legal trial simulation | Legal proceedings, case analysis | +| CouncilMeeting | Decision-making council meeting | Governance, voting processes | +| MentorshipSession | Structured mentorship interaction | Learning, guidance | +| NegotiationSession | Multi-party negotiation | Business deals, agreements | + +## OneOnOneDebate + +### Description +Simulates a turn-based debate between two agents for a specified number of loops. Each agent takes turns responding to the other's arguments. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_loops | int | Number of conversational turns | No | 1 | +| agents | List[Agent] | Two agents for debate | Yes | None | +| img | str | Optional image input | No | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes debate between agents | + +### Example + +Full example: [Philosophy Discussion Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/philosophy_discussion_example.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import OneOnOneDebate + +# Create debating agents +agent1 = Agent(name="Philosopher1") +agent2 = Agent(name="Philosopher2") + +# Initialize debate +debate = OneOnOneDebate( + max_loops=3, + agents=[agent1, agent2] +) + +# Run debate +result = debate.run("Is artificial intelligence consciousness possible?") +``` + +## ExpertPanelDiscussion + +### Description +Simulates an expert panel discussion with a moderator guiding the conversation. Multiple experts provide insights on a topic with structured rounds. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_rounds | int | Number of discussion rounds | No | 3 | +| agents | List[Agent] | Expert panel participants | Yes | None | +| moderator | Agent | Discussion moderator | Yes | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes panel discussion | + +### Example + +Full example: [Healthcare Panel Discussion](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/healthcare_panel_discussion.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import ExpertPanelDiscussion + +# Create expert agents +moderator = Agent(name="Moderator") +expert1 = Agent(name="AI_Expert") +expert2 = Agent(name="Ethics_Expert") +expert3 = Agent(name="Neuroscience_Expert") + +# Initialize panel +panel = ExpertPanelDiscussion( + max_rounds=2, + agents=[expert1, expert2, expert3], + moderator=moderator +) + +# Run panel discussion +result = panel.run("What are the ethical implications of AGI development?") +``` + +## RoundTableDiscussion + +### Description +Simulates a round table where each participant speaks in order, then the cycle repeats. Facilitated discussion with equal participation. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| max_cycles | int | Number of speaking cycles | No | 2 | +| agents | List[Agent] | Round table participants | Yes | None | +| facilitator | Agent | Discussion facilitator | Yes | None | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes round table discussion | + +### Example + +Full example: [AI Ethics Debate](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/ai_ethics_debate.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import RoundTableDiscussion + +# Create participants +facilitator = Agent(name="Facilitator") +participant1 = Agent(name="Participant1") +participant2 = Agent(name="Participant2") +participant3 = Agent(name="Participant3") + +# Initialize round table +roundtable = RoundTableDiscussion( + max_cycles=2, + agents=[participant1, participant2, participant3], + facilitator=facilitator +) + +# Run discussion +result = roundtable.run("How can we improve renewable energy adoption?") +``` + +## InterviewSeries + +### Description +Conducts a structured interview with follow-up questions. Systematic Q&A with depth through follow-up questions. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| questions | List[str] | Prepared interview questions | No | Default questions | +| interviewer | Agent | Interviewer agent | Yes | None | +| interviewee | Agent | Interviewee agent | Yes | None | +| follow_up_depth | int | Follow-up questions per main question | No | 2 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes interview series | + +### Example + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import InterviewSeries + +# Create agents +interviewer = Agent(name="Interviewer") +interviewee = Agent(name="Expert") + +# Prepare questions +questions = [ + "What is your background in AI?", + "How do you see AI evolving in the next decade?", + "What are the biggest challenges in AI development?" +] + +# Initialize interview +interview = InterviewSeries( + questions=questions, + interviewer=interviewer, + interviewee=interviewee, + follow_up_depth=2 +) + +# Run interview +result = interview.run("AI Development and Future Prospects") +``` + +## PeerReviewProcess + +### Description +Simulates academic peer review with multiple reviewers and author responses. Structured feedback and revision process. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| reviewers | List[Agent] | Reviewer agents | Yes | None | +| author | Agent | Author agent | Yes | None | +| review_rounds | int | Number of review rounds | No | 2 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes peer review process | + +### Example + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import PeerReviewProcess + +# Create agents +author = Agent(name="Author") +reviewer1 = Agent(name="Reviewer1") +reviewer2 = Agent(name="Reviewer2") + +# Initialize peer review +review = PeerReviewProcess( + reviewers=[reviewer1, reviewer2], + author=author, + review_rounds=2 +) + +# Run review process +result = review.run("New Machine Learning Algorithm for Natural Language Processing") +``` + +## MediationSession + +### Description +Simulates a mediation session to resolve conflicts between parties. Facilitated conflict resolution with structured sessions. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| parties | List[Agent] | Disputing parties | Yes | None | +| mediator | Agent | Mediator agent | Yes | None | +| max_sessions | int | Number of mediation sessions | No | 3 | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes mediation session | + +### Example + +Full example: [Merger Mediation Session](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/merger_mediation_session.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import MediationSession + +# Create agents +mediator = Agent(name="Mediator") +party1 = Agent(name="Party1") +party2 = Agent(name="Party2") + +# Initialize mediation +mediation = MediationSession( + parties=[party1, party2], + mediator=mediator, + max_sessions=3 +) + +# Run mediation +result = mediation.run("Resolve intellectual property dispute") +``` + +## BrainstormingSession + +### Description +Simulates a brainstorming session where participants build on each other's ideas. Creative idea generation with collaborative building. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| participants | List[Agent] | Brainstorming participants | Yes | None | +| facilitator | Agent | Session facilitator | Yes | None | +| idea_rounds | int | Number of idea generation rounds | No | 3 | +| build_on_ideas | bool | Whether to build on previous ideas | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes brainstorming session | + +### Example + +Full example: [Pharma Research Brainstorm](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/pharma_research_brainstorm.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import BrainstormingSession + +# Create agents +facilitator = Agent(name="Facilitator") +participant1 = Agent(name="Creative1") +participant2 = Agent(name="Creative2") +participant3 = Agent(name="Creative3") + +# Initialize brainstorming +brainstorm = BrainstormingSession( + participants=[participant1, participant2, participant3], + facilitator=facilitator, + idea_rounds=3, + build_on_ideas=True +) + +# Run brainstorming +result = brainstorm.run("Innovative solutions for urban transportation") +``` + +## TrialSimulation + +### Description +Simulates a legal trial with structured phases and roles. Complete legal proceeding simulation with all participants. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| prosecution | Agent | Prosecution attorney | Yes | None | +| defense | Agent | Defense attorney | Yes | None | +| judge | Agent | Trial judge | Yes | None | +| witnesses | List[Agent] | Trial witnesses | No | None | +| phases | List[str] | Trial phases | No | Default phases | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes trial simulation | + +### Example + +Full example: [Medical Malpractice Trial](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/medical_malpractice_trial.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import TrialSimulation + +# Create agents +judge = Agent(name="Judge") +prosecutor = Agent(name="Prosecutor") +defense = Agent(name="Defense") +witness1 = Agent(name="Witness1") +witness2 = Agent(name="Witness2") + +# Initialize trial +trial = TrialSimulation( + prosecution=prosecutor, + defense=defense, + judge=judge, + witnesses=[witness1, witness2], + phases=["opening", "testimony", "cross", "closing"] +) + +# Run trial +result = trial.run("Patent infringement case") +``` + +## CouncilMeeting + +### Description +Simulates a council meeting with structured discussion and decision-making. Governance process with voting and consensus building. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| council_members | List[Agent] | Council participants | Yes | None | +| chairperson | Agent | Meeting chairperson | Yes | None | +| voting_rounds | int | Number of voting rounds | No | 1 | +| require_consensus | bool | Whether consensus is required | No | False | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes council meeting | + +### Example + +Full example: [Investment Council Meeting](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/investment_council_meeting.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import CouncilMeeting + +# Create agents +chairperson = Agent(name="Chair") +member1 = Agent(name="Member1") +member2 = Agent(name="Member2") +member3 = Agent(name="Member3") + +# Initialize council meeting +council = CouncilMeeting( + council_members=[member1, member2, member3], + chairperson=chairperson, + voting_rounds=2, + require_consensus=True +) + +# Run meeting +result = council.run("Vote on new environmental policy") +``` + +## MentorshipSession + +### Description +Simulates a mentorship session with structured learning and feedback. Guided learning process with progress tracking. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| mentor | Agent | Mentor agent | Yes | None | +| mentee | Agent | Mentee agent | Yes | None | +| session_count | int | Number of sessions | No | 3 | +| include_feedback | bool | Whether to include feedback | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes mentorship session | + +### Example + +Full example: [Startup Mentorship Program](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/startup_mentorship_program.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import MentorshipSession + +# Create agents +mentor = Agent(name="Mentor") +mentee = Agent(name="Mentee") + +# Initialize mentorship +mentorship = MentorshipSession( + mentor=mentor, + mentee=mentee, + session_count=3, + include_feedback=True +) + +# Run session +result = mentorship.run("Career development in AI research") +``` + +## NegotiationSession + +### Description +Simulates a negotiation with multiple parties working toward agreement. Complex multi-party negotiation with concessions. + +### Parameters + +| Parameter | Type | Description | Required | Default | +|-----------|------|-------------|----------|---------| +| parties | List[Agent] | Negotiating parties | Yes | None | +| mediator | Agent | Negotiation mediator | Yes | None | +| negotiation_rounds | int | Number of rounds | No | 5 | +| include_concessions | bool | Whether to allow concessions | No | True | +| output_type | str | Format for conversation history | No | "str-all-except-first" | + +### Run Method + +| Method | Parameters | Returns | Description | +|--------|------------|---------|-------------| +| run | task: str | list | Executes negotiation session | + +### Example + +Full example: [NVIDIA-AMD Executive Negotiation](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/nvidia_amd_executive_negotiation.py) + +```python +from swarms.agents import Agent +from swarms.structs.multi_agent_debates import NegotiationSession + +# Create agents +mediator = Agent(name="Mediator") +party1 = Agent(name="Company1") +party2 = Agent(name="Company2") + +# Initialize negotiation +negotiation = NegotiationSession( + parties=[party1, party2], + mediator=mediator, + negotiation_rounds=4, + include_concessions=True +) + +# Run negotiation +result = negotiation.run("Merger terms negotiation") +``` + +## Conclusion + +The multi-agent orchestration methods in Swarms provide powerful frameworks for structuring complex interactions between AI agents. Key benefits include: + +1. Structured Communication: Each method provides a clear framework for organizing multi-agent interactions +2. Role-Based Interactions: Agents can take on specific roles with defined responsibilities +3. Flexible Configuration: Customizable parameters for controlling interaction flow +4. Scalable Architecture: Support for various numbers of participants and interaction rounds +5. Comprehensive Coverage: Methods for different use cases from debates to negotiations +6. Professional Output: Consistent formatting and organization of conversation history +7. Easy Integration: Simple API for incorporating into larger applications \ No newline at end of file