[DOCS] Comprehensive guide for Agent output formats and Swarm architecture response types

[kyegomez]

Create comprehensive documentation educating users about the various output formats available in agent.py and all swarm architectures (SwarmRouter, SequentialWorkflow, ConcurrentWorkflow, etc.), including their response types, streaming capabilities, and usage patterns.

Background

Swarms provides extensive output format customization across 15+ output types and 11+ swarm architectures, but this flexibility is not well-documented. Users need clear guidance on:

1. What output formats are available
2. When to use each format
3. How swarm architectures differ in their outputs
4. Streaming capabilities and callbacks
5. Response schemas and structured outputs

Current State

Output Formats Available (swarms/utils/output_types.py)

The framework supports 15+ output types:

HistoryOutputType = Literal[
    "list",              # Returns conversation as a list of message dicts
    "dict",              # Returns conversation as a dictionary
    "dictionary",        # Alias for dict
    "string",            # Returns conversation as a string
    "str",               # Alias for string
    "final",             # Returns content of the final message only
    "last",              # Alias for final
    "json",              # Returns conversation as JSON string
    "all",               # Returns conversation as string (same as "string")
    "yaml",              # Returns conversation as YAML string
    "xml",               # Returns conversation as XML string
    "dict-all-except-first",    # Returns all messages except first as dict
    "str-all-except-first",     # Returns all messages except first as string
    "basemodel",         # Returns as BaseModel
    "dict-final",        # Returns final message as a dictionary
    "list-final",        # Returns final message as a list
]

Swarm Architectures Summary

Swarm Type	Default Output	Execution Model	Key Feature	File Location
SequentialWorkflow	dict	Sequential	Agent-to-agent passing	swarms/structs/sequential_workflow.py
ConcurrentWorkflow	dict-all-except-first	Threaded	Dashboard + streaming	swarms/structs/concurrent_workflow.py
SwarmRouter	dict-all-except-first	Routed	18 swarm types	swarms/structs/swarm_router.py
AgentRearrange	all	Custom flow	Flexible patterns	swarms/structs/agent_rearrange.py
MixtureOfAgents	final	Multi-layer	Aggregator synthesis	swarms/structs/mixture_of_agents.py

• should be in the examples section of mkdocs
• should be simple, and show the agent.py examples with maybe one or 2 multi agent architectures