diff --git a/docs/user-guide/concepts/multi-agent/graph.md b/docs/user-guide/concepts/multi-agent/graph.md index f7b081a5..c75e5239 100644 --- a/docs/user-guide/concepts/multi-agent/graph.md +++ b/docs/user-guide/concepts/multi-agent/graph.md @@ -1,6 +1,23 @@ -# Agent Graphs: Building Multi-Agent Systems +# Graph Multi-Agent Pattern -An agent graph is a structured network of interconnected AI agents designed to solve complex problems through coordinated collaboration. Each agent represents a specialized node with specific capabilities, and the connections between agents define explicit communication pathways. +A Graph is a deterministic Directed Acyclic Graph (DAG) based agent orchestration system where agents or other multi-agent systems (like [Swarm](./swarm.md) or nested Graphs) are nodes in a graph. Nodes are executed according to edge dependencies, with output from one node passed as input to connected nodes. + +- **Deterministic execution order** based on DAG structure +- **Output propagation** along edges between nodes +- **Clear dependency management** between agents +- **Supports nested patterns** (Graph as a node in another Graph) +- **Conditional edge traversal** for dynamic workflows +- **Multi-modal input support** for handling text, images, and other content types + +## How Graphs Work + +The Graph pattern operates on the principle of structured, deterministic workflows where: + +1. Nodes represent agents or multi-agent systems +2. Edges define dependencies and information flow between nodes +3. Execution follows a topological sort of the graph +4. Output from one node becomes input for dependent nodes +5. Entry points receive the original task as input ```mermaid graph TD @@ -10,300 +27,342 @@ graph TD C --> D ``` -Agent graphs provide precise control over information flow, allowing developers to create sophisticated multi-agent systems with predictable behavior patterns and specialized agent roles. +## Graph Components -### Components of an Agent Graph +### 1. GraphNode -An agent graph consists of three primary components: +A [`GraphNode`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphNode) represents a node in the graph with: -#### 1. Nodes (Agents) +- **node_id**: Unique identifier for the node +- **executor**: The Agent or MultiAgentBase instance to execute +- **dependencies**: Set of nodes this node depends on +- **execution_status**: Current status (PENDING, EXECUTING, COMPLETED, FAILED) +- **result**: The NodeResult after execution +- **execution_time**: Time taken to execute the node in milliseconds -Nodes represent individual AI agents with: +### 2. GraphEdge -- **Identity**: Unique identifier within the graph -- **Role**: Specialized function or purpose -- **System Prompt**: Instructions defining the agent's behavior -- **Tools**: Capabilities available to the agent -- **Message Queue**: Buffer for incoming communications +A [`GraphEdge`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphEdge) represents a connection between nodes with: -#### 2. Edges (Connections) +- **from_node**: Source node +- **to_node**: Target node +- **condition**: Optional function that determines if the edge should be traversed -Edges define the communication pathways between agents: +### 3. GraphBuilder - - **Direction**: One-way or bidirectional information flow - - **Relationship**: How agents relate to each other (e.g., supervisor/worker) - - **Message Passing**: The mechanism for transferring information +The [`GraphBuilder`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphBuilder) provides a simple interface for constructing graphs: -#### 3. Topology Patterns +- **add_node()**: Add an agent or multi-agent system as a node +- **add_edge()**: Create a dependency between nodes +- **set_entry_point()**: Define starting nodes for execution +- **build()**: Validate and create the Graph instance -##### Star Topology -A central coordinator with radiating specialists, ideal for centralized workflows like content creation with editorial oversight or customer service with escalation paths. +## Creating a Graph -```mermaid -graph TD - Coordinator[Coordinator] - Specialist1[Specialist 1] - Specialist2[Specialist 2] - Specialist3[Specialist 3] - - Coordinator --> Specialist1 - Coordinator --> Specialist2 - Coordinator --> Specialist3 -``` +To create a [`Graph`](../../../api-reference/multiagent.md#strands.multiagent.graph.Graph), you use the [`GraphBuilder`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphBuilder) to define nodes, edges, and entry points: + +```python +from strands import Agent +from strands.multiagent import GraphBuilder -##### Mesh Topology -Fully connected network where all agents can communicate directly with each other, ideal for collaborative problem-solving, debates, and consensus-building. +# Create specialized agents +researcher = Agent(name="researcher", system_prompt="You are a research specialist...") +analyst = Agent(name="analyst", system_prompt="You are a data analysis specialist...") +fact_checker = Agent(name="fact_checker", system_prompt="You are a fact checking specialist...") +report_writer = Agent(name="report_writer", system_prompt="You are a report writing specialist...") -```mermaid -graph TD - AgentA[Agent A] - AgentB[Agent B] - AgentC[Agent C] - AgentD[Agent D] - AgentE[Agent E] - - AgentA <--> AgentB - AgentA <--> AgentC - AgentB <--> AgentC - AgentC <--> AgentD - AgentC <--> AgentE - AgentD <--> AgentE +# Build the graph +builder = GraphBuilder() + +# Add nodes +builder.add_node(researcher, "research") +builder.add_node(analyst, "analysis") +builder.add_node(fact_checker, "fact_check") +builder.add_node(report_writer, "report") + +# Add edges (dependencies) +builder.add_edge("research", "analysis") +builder.add_edge("research", "fact_check") +builder.add_edge("analysis", "report") +builder.add_edge("fact_check", "report") + +# Set entry points (optional - will be auto-detected if not specified) +builder.set_entry_point("research") + +# Build the graph +graph = builder.build() + +# Execute the graph on a task +result = graph("Research the impact of AI on healthcare and create a comprehensive report") + +# Access the results +print(f"\nStatus: {result.status}") +print(f"Execution order: {[node.node_id for node in result.execution_order]}") ``` -##### Hierarchical Topology -Tree structure with parent-child relationships, ideal for layered processing, project management with task delegation, and multi-level review processes. +## Conditional Edges -```mermaid -graph TD - Executive[Executive] - Manager1[Manager 1] - Manager2[Manager 2] - Worker1[Worker 1] - Worker2[Worker 2] - Worker3[Worker 3] - Worker4[Worker 4] +You can add conditional logic to edges to create dynamic workflows: + +```python +def only_if_research_successful(state): + """Only traverse if research was successful.""" + research_node = state.results.get("research") + if not research_node: + return False - Executive --> Manager1 - Executive --> Manager2 - Manager1 --> Worker1 - Manager1 --> Worker2 - Manager2 --> Worker3 - Manager2 --> Worker4 + # Check if research result contains success indicator + result_text = str(research_node.result) + return "successful" in result_text.lower() + +# Add conditional edge +builder.add_edge("research", "analysis", condition=only_if_research_successful) ``` -### When to Use Agent Graphs +## Nested Multi-Agent Patterns -Agent graphs are ideal for: +You can use a [`Graph`](../../../api-reference/multiagent.md#strands.multiagent.graph.Graph) or [`Swarm`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm) as a node within another Graph: -1. **Complex Communication Patterns**: Custom topologies and interaction patterns -2. **Persistent Agent State**: Long-running agent networks that maintain context -3. **Specialized Agent Roles**: Different agents with distinct capabilities -4. **Fine-Grained Control**: Precise management of information flow +```python +from strands import Agent +from strands.multiagent import GraphBuilder, Swarm -## Implementing Agent Graphs with Strands +# Create a swarm of research agents +research_agents = [ + Agent(name="medical_researcher", system_prompt="You are a medical research specialist..."), + Agent(name="technology_researcher", system_prompt="You are a technology research specialist..."), + Agent(name="economic_researcher", system_prompt="You are an economic research specialist...") +] +research_swarm = Swarm(research_agents) -### Hierarchical Agent Graph Example +# Create a single agent node too +analyst = Agent(system_prompt="Analyze the provided research.") -To illustrate the hierarchical topology pattern discussed above, the following example implements a three-level organizational structure with specialized roles. This hierarchical approach demonstrates one of the key topology patterns for agent graphs, showing how information flows through a tree-like structure with clear parent-child relationships. +# Create a graph with the swarm as a node +builder = GraphBuilder() +builder.add_node(research_swarm, "research_team") +builder.add_node(analyst, "analysis") +builder.add_edge("research_team", "analysis") -```mermaid -graph TD - A((Executive
Coordinator)) --> B((Economic
Department)) - A --> C((Technical
Analyst)) - A --> D((Social
Analyst)) - B --> E((Market
Research)) - B --> F((Financial
Analysis)) - - E -.-> B - F -.-> B - B -.-> A - C -.-> A - D -.-> A +graph = builder.build() + +result = graph("Research the impact of AI on healthcare and create a comprehensive report") + +# Access the results +print(f"\n{result}") ``` -#### 1. Level 1 - Executive Coordinator +## Multi-Modal Input Support + +Graphs support multi-modal inputs like text and images using [`ContentBlocks`](../../../api-reference/types.md#strands.types.content.ContentBlock): ```python -from strands import Agent, tool - -# Level 1 - Executive Coordinator -COORDINATOR_SYSTEM_PROMPT = """You are an executive coordinator who oversees complex analyses across multiple domains. -For economic questions, use the economic_department tool. -For technical questions, use the technical_analysis tool. -For social impact questions, use the social_analysis tool. -Synthesize all analyses into comprehensive executive summaries. - -Your process should be: -1. Determine which domains are relevant to the query (economic, technical, social) -2. Collect analysis from each relevant domain using the appropriate tools -3. Synthesize the information into a cohesive executive summary -4. Present findings with clear structure and organization - -Always consider multiple perspectives and provide balanced, well-rounded assessments. -""" - -# Create the coordinator agent with all tools -coordinator = Agent( - system_prompt=COORDINATOR_SYSTEM_PROMPT, - tools=[economic_department, technical_analysis, social_analysis], - callback_handler=None -) - -# Process a complex task through the hierarchical agent graph -def process_complex_task(task): - """Process a complex task through the multi-level hierarchical agent graph""" - return coordinator(f"Provide a comprehensive analysis of: {task}") +from strands import Agent +from strands.multiagent import GraphBuilder +from strands.types.content import ContentBlock + +# Create agents for image processing workflow +image_analyzer = Agent(system_prompt="You are an image analysis expert...") +summarizer = Agent(system_prompt="You are a summarization expert...") + +# Build the graph +builder = GraphBuilder() +builder.add_node(image_analyzer, "image_analyzer") +builder.add_node(summarizer, "summarizer") +builder.add_edge("image_analyzer", "summarizer") +builder.set_entry_point("image_analyzer") + +graph = builder.build() + +# Create content blocks with text and image +content_blocks = [ + ContentBlock(text="Analyze this image and describe what you see:"), + ContentBlock(image={"format": "png", "source": {"bytes": image_bytes}}), +] + +# Execute the graph with multi-modal input +result = graph(content_blocks) ``` -#### 2. Level 2 - Mid-level Manager Agent +## Asynchronous Execution + +You can also execute a Graph asynchronously by calling the [`invoke_async`](../../../api-reference/multiagent.md#strands.multiagent.graph.Graph.invoke_async) function: ```python -# Level 2 - Mid-level Manager Agent with its own specialized tools -@tool -def economic_department(query: str) -> str: - """Coordinate economic analysis across market and financial domains.""" - print("📈 Economic Department coordinating analysis...") - econ_manager = Agent( - system_prompt="""You are an economic department manager who coordinates specialized economic analyses. - For market-related questions, use the market_research tool. - For financial questions, use the financial_analysis tool. - Synthesize the results into a cohesive economic perspective. - - Important: Make sure to use both tools for comprehensive analysis unless the query is clearly focused on just one area. - """, - tools=[market_research, financial_analysis], - callback_handler=None - ) - return str(econ_manager(query)) +import asyncio + +async def run_graph(): + result = await graph.invoke_async("Research and analyze market trends...") + return result + +result = asyncio.run(run_graph()) ``` -#### 3. Level 3 - Specialized Analysis Agents +## Graph Results + +When a Graph completes execution, it returns a [`GraphResult`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphResult) object with detailed information: ```python -# Level 3 - Specialized Analysis Agents -@tool -def market_research(query: str) -> str: - """Analyze market trends and consumer behavior.""" - print("🔍 Market Research Specialist analyzing...") - market_agent = Agent( - system_prompt="You are a market research specialist who analyzes consumer trends, market segments, and purchasing behaviors. Provide detailed insights on market conditions, consumer preferences, and emerging trends.", - callback_handler=None - ) - return str(market_agent(query)) - -@tool -def financial_analysis(query: str) -> str: - """Analyze financial aspects and economic implications.""" - print("💹 Financial Analyst processing...") - financial_agent = Agent( - system_prompt="You are a financial analyst who specializes in economic forecasting, cost-benefit analysis, and financial modeling. Provide insights on financial viability, economic impacts, and budgetary considerations.", - callback_handler=None - ) - return str(financial_agent(query)) - -@tool -def technical_analysis(query: str) -> str: - """Analyze technical feasibility and implementation challenges.""" - print("⚙️ Technical Analyst evaluating...") - tech_agent = Agent( - system_prompt="You are a technology analyst who evaluates technical feasibility, implementation challenges, and emerging technologies. Provide detailed assessments of technical aspects, implementation requirements, and potential technological hurdles.", - callback_handler=None - ) - return str(tech_agent(query)) - -@tool -def social_analysis(query: str) -> str: - """Analyze social impacts and behavioral implications.""" - print("👥 Social Impact Analyst investigating...") - social_agent = Agent( - system_prompt="You are a social impact analyst who focuses on how changes affect communities, behaviors, and social structures. Provide insights on social implications, behavioral changes, and community impacts.", - callback_handler=None - ) - return str(social_agent(query)) +result = graph("Research and analyze...") + +# Check execution status +print(f"Status: {result.status}") # COMPLETED, FAILED, etc. + +# See which nodes were executed and in what order +for node in result.execution_order: + print(f"Executed: {node.node_id}") + +# Get results from specific nodes +analysis_result = result.results["analysis"].result +print(f"Analysis: {analysis_result}") + +# Get performance metrics +print(f"Total nodes: {result.total_nodes}") +print(f"Completed nodes: {result.completed_nodes}") +print(f"Failed nodes: {result.failed_nodes}") +print(f"Execution time: {result.execution_time}ms") +print(f"Token usage: {result.accumulated_usage}") ``` -This implementation demonstrates a hierarchical agent graph architecture where: +## Input Propagation -1. **Multi-Level Hierarchy**: Three distinct levels form a clear organizational structure: +The Graph automatically builds input for each node based on its dependencies: - - Level 1: Executive Coordinator oversees the entire analysis process - - Level 2: Department Manager (Economic Department) coordinates its own team of specialists - - Level 3: Specialist Analysts provide domain-specific expertise +1. **Entry point nodes** receive the original task as input +2. **Dependent nodes** receive a combined input that includes: + - The original task + - Results from all dependency nodes that have completed execution -2. **Tool-Based Communication**: Agents communicate through the tool mechanism, where higher-level agents invoke lower-level agents as tools, creating a structured information flow path. +This ensures each node has access to both the original context and the outputs from its dependencies. -3. **Nested Delegation**: The Executive Coordinator delegates to both the Economic Department and individual specialists. The Economic Department further delegates to its own specialists, demonstrating nested responsibility. +The formatted input for dependent nodes looks like: -4. **Specialized Domains**: Each branch focuses on different domains (economic, technical, social), with the Economic Department having its own sub-specialties (market research and financial analysis). +``` +Original Task: [The original task text] -5. **Information Synthesis**: Each level aggregates and synthesizes information from lower levels before passing it upward, adding value at each stage of the hierarchy. +Inputs from previous nodes: -## Using the Agent Graph Tool +From [node_id]: + - [Agent name]: [Result text] + - [Agent name]: [Another result text] -Strands Agents SDK provides a built-in `agent_graph` tool that simplifies multi-agent system implementation. The full implementation can be found in the [Strands Tools repository](https://github.com/strands-agents/tools/blob/main/src/strands_tools/agent_graph.py). +From [another_node_id]: + - [Agent name]: [Result text] +``` -### Creating and Using Agent Graphs +## Graphs as a Tool + +Agents can dynamically create and orchestrate graphs by using the `graph` tool available in the [Strands tools package](../tools/example-tools-package.md). ```python from strands import Agent from strands_tools import agent_graph -# Create an agent with agent_graph capability -agent = Agent(tools=[agent_graph]) - -# Create a research team with a star topology -result = agent.tool.agent_graph( - action="create", - graph_id="research_team", - topology={ - "type": "star", - "nodes": [ - { - "id": "coordinator", - "role": "team_lead", - "system_prompt": "You are a research team leader coordinating specialists." - }, - { - "id": "data_analyst", - "role": "analyst", - "system_prompt": "You are a data analyst specializing in statistical analysis." - }, - { - "id": "domain_expert", - "role": "expert", - "system_prompt": "You are a domain expert with deep subject knowledge." - } - ], - "edges": [ - {"from": "coordinator", "to": "data_analyst"}, - {"from": "coordinator", "to": "domain_expert"}, - {"from": "data_analyst", "to": "coordinator"}, - {"from": "domain_expert", "to": "coordinator"} - ] - } -) - -# Send a task to the coordinator -agent.tool.agent_graph( - action="message", - graph_id="research_team", - message={ - "target": "coordinator", - "content": "Analyze the impact of remote work on productivity." - } -) +agent = Agent(tools=[agent_graph], system_prompt="Create a graph of agents to solve the user's query.") + +agent("Design a TypeScript REST API and then write the code for it") +``` + +In this example: + +1. The agent uses the `graph` tool to dynamically create nodes and edges in a graph. These nodes might be architect, coder, and reviewer agents with edges defined as architect -> coder -> reviewer +2. Next the agent executes the graph +3. The agent analyzes the graph results and then decides to either create another graph and execute it, or answer the user's query + +## Common Graph Topologies + +### 1. Sequential Pipeline + +```mermaid +graph LR + A[Research] --> B[Analysis] --> C[Review] --> D[Report] ``` -### Key Actions +```python +builder = GraphBuilder() +builder.add_node(researcher, "research") +builder.add_node(analyst, "analysis") +builder.add_node(reviewer, "review") +builder.add_node(report_writer, "report") + +builder.add_edge("research", "analysis") +builder.add_edge("analysis", "review") +builder.add_edge("review", "report") +``` -The agent_graph tool supports five primary actions: +### 2. Parallel Processing with Aggregation -1. **create**: Build a new agent network with the specified topology -2. **message**: Send information to a specific agent in the network -3. **status**: Check the current state of an agent network -4. **list**: View all active agent networks -5. **stop**: Terminate an agent network when it's no longer needed +```mermaid +graph TD + A[Coordinator] --> B[Worker 1] + A --> C[Worker 2] + A --> D[Worker 3] + B --> E[Aggregator] + C --> E + D --> E +``` + +```python +builder = GraphBuilder() +builder.add_node(coordinator, "coordinator") +builder.add_node(worker1, "worker1") +builder.add_node(worker2, "worker2") +builder.add_node(worker3, "worker3") +builder.add_node(aggregator, "aggregator") + +builder.add_edge("coordinator", "worker1") +builder.add_edge("coordinator", "worker2") +builder.add_edge("coordinator", "worker3") +builder.add_edge("worker1", "aggregator") +builder.add_edge("worker2", "aggregator") +builder.add_edge("worker3", "aggregator") +``` + +### 3. Branching Logic + +```mermaid +graph TD + A[Classifier] --> B[Technical Branch] + A --> C[Business Branch] + B --> D[Technical Report] + C --> E[Business Report] +``` + +```python +def is_technical(state): + classifier_result = state.results.get("classifier") + if not classifier_result: + return False + result_text = str(classifier_result.result) + return "technical" in result_text.lower() + +def is_business(state): + classifier_result = state.results.get("classifier") + if not classifier_result: + return False + result_text = str(classifier_result.result) + return "business" in result_text.lower() + +builder = GraphBuilder() +builder.add_node(classifier, "classifier") +builder.add_node(tech_specialist, "tech_specialist") +builder.add_node(business_specialist, "business_specialist") +builder.add_node(tech_report, "tech_report") +builder.add_node(business_report, "business_report") + +builder.add_edge("classifier", "tech_specialist", condition=is_technical) +builder.add_edge("classifier", "business_specialist", condition=is_business) +builder.add_edge("tech_specialist", "tech_report") +builder.add_edge("business_specialist", "business_report") +``` -## Conclusion +## Best Practices -Agent graphs provide a structured approach to building multi-agent systems with precise control over information flow and agent interactions. By organizing agents into topologies like star, mesh, or hierarchical patterns, developers can create sophisticated systems tailored to specific tasks. The Strands Agents SDK supports both custom implementations through tool-based communication and simplified creation via the agent_graph tool. Whether implementing specialized hierarchies with nested delegation or dynamic networks with persistent state, agent graphs enable complex problem-solving through coordinated collaboration of specialized AI agents working within well-defined communication pathways. +1. **Design for acyclicity**: Ensure your graph has no cycles +2. **Use meaningful node IDs**: Choose descriptive names for nodes +3. **Validate graph structure**: The builder will check for cycles and validate entry points +4. **Handle node failures**: Consider how failures in one node affect the overall workflow +5. **Use conditional edges**: For dynamic workflows based on intermediate results +6. **Consider parallelism**: Independent branches can execute concurrently +7. **Nest multi-agent patterns**: Use Swarms within Graphs for complex workflows +8. **Leverage multi-modal inputs**: Use ContentBlocks for rich inputs including images diff --git a/docs/user-guide/concepts/multi-agent/swarm.md b/docs/user-guide/concepts/multi-agent/swarm.md index a14932ca..bc67f3a6 100644 --- a/docs/user-guide/concepts/multi-agent/swarm.md +++ b/docs/user-guide/concepts/multi-agent/swarm.md @@ -1,249 +1,246 @@ -# Multi-Agent Systems and Swarm Intelligence +# Swarm Multi-Agent Pattern -An agent swarm is a collection of autonomous AI agents working together to solve complex problems through collaboration. Inspired by natural systems like ant colonies or bird flocks, agent swarms leverage collective intelligence where the combined output exceeds what any single agent could produce. By distributing tasks and sharing information, swarms can tackle complex problems more efficiently and effectively than individual agents working in isolation. +A Swarm is a collaborative agent orchestration system where multiple agents work together as a team to solve complex tasks. Unlike traditional sequential or hierarchical multi-agent systems, a Swarm enables autonomous coordination between agents with shared context and working memory. -Multi-agent systems consist of multiple interacting intelligent agents within an environment. These systems enable: +- **Self-organizing agent teams** with shared working memory +- **Tool-based coordination** between agents +- **Autonomous agent collaboration** without central control +- **Dynamic task distribution** based on agent capabilities +- **Collective intelligence** through shared context +- **Multi-modal input support** for handling text, images, and other content types -- **Distributed Problem Solving**: Breaking complex tasks into subtasks for parallel processing -- **Information Sharing**: Agents exchange insights to build collective knowledge -- **Specialization**: Different agents focus on specific aspects of a problem -- **Redundancy**: Multiple agents working on similar tasks improve reliability -- **Emergent Intelligence**: The system exhibits capabilities beyond those of its individual components +## How Swarms Work -Swarm intelligence emphasizes: +Swarms operate on the principle of emergent intelligence - the idea that a group of specialized agents working together can solve problems more effectively than a single agent. Each agent in a Swarm: -1. **Decentralized Control**: No single agent directs the entire system -2. **Local Interactions**: Agents primarily interact with nearby agents -3. **Simple Rules**: Individual agents follow relatively simple behaviors -4. **Emergent Complexity**: Complex system behavior emerges from simple agent interactions - -### Components of a Swarm Architecture - -A swarm architecture consists of several key components: - -#### 1. Communication Patterns - -- **Mesh**: All agents can communicate with all other agents +1. Has access to the full task context +2. Can see the history of which agents have worked on the task +3. Can access shared knowledge contributed by other agents +4. Can decide when to hand off to another agent with different expertise +5. Can mark a task as complete when the objective is achieved ```mermaid graph TD - Agent1[Agent 1] <--> Agent2[Agent 2] - Agent1 <--> Agent3[Agent 3] - Agent2 <--> Agent3 + Researcher <--> Reviewer + Researcher <--> Architect + Reviewer <--> Architect + Coder <--> Researcher + Coder <--> Reviewer + Coder <--> Architect ``` -#### 2. Shared Memory Systems +## Creating a Swarm + +To create a Swarm, you need to define a collection of agents with different specializations: + +```python +from strands import Agent +from strands.multiagent import Swarm + +# Create specialized agents +researcher = Agent(name="researcher", system_prompt="You are a research specialist...") +coder = Agent(name="coder", system_prompt="You are a coding specialist...") +reviewer = Agent(name="reviewer", system_prompt="You are a code review specialist...") +architect = Agent(name="architect", system_prompt="You are a system architecture specialist...") + +# Create a swarm with these agents +swarm = Swarm( + [researcher, coder, reviewer, architect], + max_handoffs=20, + max_iterations=20, + execution_timeout=900.0, # 15 minutes + node_timeout=300.0, # 5 minutes per agent + repetitive_handoff_detection_window=8, # There must be >= 3 unique agents in the last 8 handoffs + repetitive_handoff_min_unique_agents=3 +) -For agents to collaborate effectively, they need mechanisms to share information: +# Execute the swarm on a task +result = swarm("Design and implement a simple REST API for a todo app") -- **Centralized Knowledge Repositories**: Common storage for collective insights -- **Message Passing Systems**: Direct communication between agents -- **Blackboard Systems**: Shared workspace where agents post and read information +# Access the final result +print(f"Status: {result.status}") +print(f"Node history: {[node.node_id for node in result.node_history]}") +``` -#### 3. Coordination Mechanisms +In this example: -Swarms require coordination to ensure agents work together effectively: +1. The `researcher` might start by handing off to the `architect` +2. The `architect` designs an API and system architecture +3. Handoff to the `coder` to implement the API and architecture +4. The `coder` writes the code +5. Handoff to the `reviewer` for code review +6. Finally, the `reviewer` completes the task with the final result -- **Collaborative**: Agents build upon others' insights and seek consensus -- **Competitive**: Agents develop independent solutions and unique perspectives -- **Hybrid**: Balances cooperation with independent exploration +## Swarm Configuration -#### 4. Task Distribution +The [`Swarm`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm) constructor allows you to control the behavior and safety parameters: -How tasks are allocated affects the swarm's efficiency: +| Parameter | Description | Default | +|-----------|-------------|---------| +| `max_handoffs` | Maximum number of agent handoffs allowed | 20 | +| `max_iterations` | Maximum total iterations across all agents | 20 | +| `execution_timeout` | Total execution timeout in seconds | 900.0 (15 min) | +| `node_timeout` | Individual agent timeout in seconds | 300.0 (5 min) | +| `repetitive_handoff_detection_window` | Number of recent nodes to check for ping-pong behavior | 0 (disabled) | +| `repetitive_handoff_min_unique_agents` | Minimum unique nodes required in recent sequence | 0 (disabled) | -- **Static Assignment**: Tasks are pre-assigned to specific agents -- **Dynamic Assignment**: Tasks are allocated based on agent availability and capability -- **Self-Organization**: Agents select tasks based on local information +## Multi-Modal Input Support +Swarms support multi-modal inputs like text and images using [`ContentBlocks`](../../../api-reference/types.md#strands.types.content.ContentBlock): -## Creating a Swarm with Strands Agents +```python +from strands import Agent +from strands.multiagent import Swarm +from strands.types.content import ContentBlock -Strands Agents SDK allows you to create swarms using existing Agent objects, even when they use different model providers or have different configurations. While various communication architectures are possible (hierarchical, parallel, sequential, and mesh), the following example demonstrates a mesh architecture implementation, which provides a flexible foundation for agent-to-agent communication. +# Create agents for image processing workflow +image_analyzer = Agent(name="image_analyzer", system_prompt="You are an image analysis expert...") +report_writer = Agent(name="report_writer", system_prompt="You are a report writing expert...") +# Create the swarm +swarm = Swarm([image_analyzer, report_writer]) -#### Mesh Swarm Architecture +# Create content blocks with text and image +content_blocks = [ + ContentBlock(text="Analyze this image and create a report about what you see:"), + ContentBlock(image={"format": "png", "source": {"bytes": image_bytes}}), +] -```mermaid -graph TD - Research[Research Agent] <---> Creative[Creative Agent] - Research <---> Critical[Critical Agent] - Creative <---> Critical - Creative <---> Summarizer[Summarizer Agent] - Critical <---> Summarizer - Research <---> Summarizer - - class Research top - class Creative,Critical middle - class Summarizer bottom +# Execute the swarm with multi-modal input +result = swarm(content_blocks) ``` -In a mesh architecture, all agents can communicate directly with each other. The following example demonstrates a swarm of specialized agents using mesh communication to solve problems collaboratively: +## Swarm Coordination Tools -```python -from strands import Agent +When you create a Swarm, each agent is automatically equipped with special tools for coordination: -# Create specialized agents with different expertise -research_agent = Agent(system_prompt=("""You are a Research Agent specializing in gathering and analyzing information. -Your role in the swarm is to provide factual information and research insights on the topic. -You should focus on providing accurate data and identifying key aspects of the problem. -When receiving input from other agents, evaluate if their information aligns with your research. -"""), -callback_handler=None) - -creative_agent = Agent(system_prompt=("""You are a Creative Agent specializing in generating innovative solutions. -Your role in the swarm is to think outside the box and propose creative approaches. -You should build upon information from other agents while adding your unique creative perspective. -Focus on novel approaches that others might not have considered. -"""), -callback_handler=None) - -critical_agent = Agent(system_prompt=("""You are a Critical Agent specializing in analyzing proposals and finding flaws. -Your role in the swarm is to evaluate solutions proposed by other agents and identify potential issues. -You should carefully examine proposed solutions, find weaknesses or oversights, and suggest improvements. -Be constructive in your criticism while ensuring the final solution is robust. -"""), -callback_handler=None) - -summarizer_agent = Agent(system_prompt="""You are a Summarizer Agent specializing in synthesizing information. -Your role in the swarm is to gather insights from all agents and create a cohesive final solution. -You should combine the best ideas and address the criticisms to create a comprehensive response. -Focus on creating a clear, actionable summary that addresses the original query effectively. -""") -``` +### 1. Handoff Tool -The mesh communication is implemented using a dictionary to track messages between agents: +Agents can transfer control to another agent when they need specialized help: ```python -# Dictionary to track messages between agents (mesh communication) -messages = { - "research": [], - "creative": [], - "critical": [], - "summarizer": [] -} +handoff_to_agent( + agent_name="coder", + message="I need help implementing this algorithm in Python", + context={"algorithm_details": "..."} +) ``` -The swarm operates in multiple phases, with each agent first analyzing the problem independently: +### 2. Completion Tool + +Any agent can mark the task as complete: ```python -# Phase 1: Initial analysis by each specialized agent -research_result = research_agent(query) -creative_result = creative_agent(query) -critical_result = critical_agent(query) +complete_swarm_task() ``` -After the initial analysis, results are shared with all other agents (mesh communication): +## Shared Context + +The Swarm maintains a shared context that all agents can access. This includes: + +- The original task description +- History of which agents have worked on the task +- Knowledge contributed by previous agents +- List of available agents for collaboration + +The formatted context for each agent looks like: -```python -# Share results with all other agents (mesh communication) -messages["creative"].append(f"From Research Agent: {research_result}") -messages["critical"].append(f"From Research Agent: {research_result}") -messages["summarizer"].append(f"From Research Agent: {research_result}") - -messages["research"].append(f"From Creative Agent: {creative_result}") -messages["critical"].append(f"From Creative Agent: {creative_result}") -messages["summarizer"].append(f"From Creative Agent: {creative_result}") - -messages["research"].append(f"From Critical Agent: {critical_result}") -messages["creative"].append(f"From Critical Agent: {critical_result}") -messages["summarizer"].append(f"From Critical Agent: {critical_result}") ``` +Handoff Message: The user needs help with Python debugging - I've identified the issue but need someone with more expertise to fix it. -In the second phase, each agent refines their solution based on input from all other agents: +User Request: My Python script is throwing a KeyError when processing JSON data from an API -```python -# Phase 2: Each agent refines based on input from others -research_prompt = f"{query}\n\nConsider these messages from other agents:\n" + "\n\n".join(messages["research"]) -creative_prompt = f"{query}\n\nConsider these messages from other agents:\n" + "\n\n".join(messages["creative"]) -critical_prompt = f"{query}\n\nConsider these messages from other agents:\n" + "\n\n".join(messages["critical"]) - -refined_research = research_agent(research_prompt) -refined_creative = creative_agent(creative_prompt) -refined_critical = critical_agent(critical_prompt) - -# Share refined results with summarizer -messages["summarizer"].append(f"From Research Agent (Phase 2): {refined_research}") -messages["summarizer"].append(f"From Creative Agent (Phase 2): {refined_creative}") -messages["summarizer"].append(f"From Critical Agent (Phase 2): {refined_critical}") +Previous agents who worked on this: data_analyst → code_reviewer + +Shared knowledge from previous agents: +• data_analyst: {"issue_location": "line 42", "error_type": "missing key validation", "suggested_fix": "add key existence check"} +• code_reviewer: {"code_quality": "good overall structure", "security_notes": "API key should be in environment variable"} + +Other agents available for collaboration: +Agent name: data_analyst. Agent description: Analyzes data and provides deeper insights +Agent name: code_reviewer. +Agent name: security_specialist. Agent description: Focuses on secure coding practices and vulnerability assessment + +You have access to swarm coordination tools if you need help from other agents or want to complete the task. ``` -Finally, the summarizer agent synthesizes all inputs into a comprehensive solution: +## Asynchronous Execution + +You can also execute a Swarm asynchronously by calling the [`invoke_async`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm.invoke_async) function: ```python -# Final phase: Summarizer creates the final solution -summarizer_prompt = f""" -Original query: {query} +import asyncio -Please synthesize the following inputs from all agents into a comprehensive final solution: +async def run_swarm(): + result = await swarm.invoke_async("Design and implement a complex system...") + return result -{"\n\n".join(messages["summarizer"])} +result = asyncio.run(run_swarm()) +``` -Create a well-structured final answer that incorporates the research findings, -creative ideas, and addresses the critical feedback. -""" +## Swarm Results -final_solution = summarizer_agent(summarizer_prompt) -``` +When a Swarm completes execution, it returns a [`SwarmResult`](../../../api-reference/multiagent.md#strands.multiagent.swarm.SwarmResult) object with detailed information: -This mesh architecture enables direct communication between all agents, allowing each agent to share insights with every other agent. The specialized roles (research, creative, critical, and summarizer) work together to produce a comprehensive solution that benefits from multiple perspectives and iterative refinement. +```python +result = swarm("Design a system architecture for...") -### Implementing Shared Memory +# Access the final result +print(f"Status: {result.status}") -While the mesh communication example effectively demonstrates agent collaboration, a shared memory system would enhance the swarm's capabilities by providing: +# Check execution status +print(f"Status: {result.status}") # COMPLETED, FAILED, etc. -- A centralized knowledge repository for all agents -- Automated phase tracking and historical knowledge preservation -- Thread-safe concurrent access for improved efficiency -- Persistent storage of insights across multiple interactions +# See which agents were involved +for node in result.node_history: + print(f"Agent: {node.node_id}") -Extending our mesh swarm example with shared memory would replace the message dictionary with a SharedMemory instance, simplifying the code while enabling more sophisticated knowledge management. +# Get results from specific nodes +analyst_result = result.results["analyst"].result +print(f"Analysis: {analyst_result}") -## Quick Start with the Swarm Tool +# Get performance metrics +print(f"Total iterations: {result.execution_count}") +print(f"Execution time: {result.execution_time}ms") +print(f"Token usage: {result.accumulated_usage}") +``` -The Strands Agents SDK provides a built-in swarm tool that simplifies the implementation of multi-agent systems, offering a quick start for users. This tool implements the shared memory concept discussed earlier, providing a more sophisticated version of what we described for extending the mesh swarm example. +## Swarm as a Tool -### Using the Swarm Tool +Agents can dynamically create and orchestrate swarms by using the `swarm` tool available in the [Strands tools package](../tools/example-tools-package.md). ```python from strands import Agent from strands_tools import swarm -# Create an agent with swarm capability -agent = Agent(tools=[swarm]) - -# Process a complex task with multiple agents in parallel -result = agent.tool.swarm( - task="Analyze this dataset and identify market trends", - swarm_size=4, - coordination_pattern="collaborative" -) +agent = Agent(tools=[swarm], system_prompt="Create a swarm of agents to solve the user's query.") -# The result contains contributions from all swarm agents -print(result["content"]) +agent("Research, analyze, and summarize the latest advancements in quantum computing") ``` -### SharedMemory Implementation - -The swarm tool implements a SharedMemory system that serves as a central knowledge repository for all agents in the swarm. This system maintains a thread-safe store where agents can record their contributions with metadata (including agent ID, content, phase, and timestamp). It tracks processing phases, allowing agents to retrieve only current-phase knowledge or access historical information. This shared memory architecture enables concurrent collaboration, maintains contribution history, and ensures smooth information flow between agents—all essential features for effective collective intelligence in a swarm. +In this example: -The full implementation of the swarm tool can be found in the [Strands Tools repository](https://github.com/strands-agents/tools/blob/main/src/strands_tools/swarm.py). +1. The agent uses the `swarm` tool to dynamically create a team of specialized agents. These might include a researcher, an analyst, and a technical writer +2. Next the agent executes the swarm +3. The swarm agents collaborate autonomously, handing off to each other as needed +4. The agent analyzes the swarm results and provides a comprehensive response to the user -### Key Parameters +## Safety Mechanisms -- **task**: The main task to be processed by the swarm -- **swarm_size**: Number of agents in the swarm (1-10) -- **coordination_pattern**: How agents should coordinate - - **collaborative**: Agents build upon others' insights - - **competitive**: Agents develop independent solutions - - **hybrid**: Balances cooperation with independent exploration +Swarms include several safety mechanisms to prevent infinite loops and ensure reliable execution: -### How the Swarm Tool Works +1. **Maximum handoffs**: Limits how many times control can be transferred between agents +2. **Maximum iterations**: Caps the total number of execution iterations +3. **Execution timeout**: Sets a maximum total runtime for the Swarm +4. **Node timeout**: Limits how long any single agent can run +5. **Repetitive handoff detection**: Prevents agents from endlessly passing control back and forth -1. **Initialization**: Creates a swarm with shared memory and specialized agents -2. **Phase Processing**: Agents work in parallel using ThreadPoolExecutor -3. **Knowledge Sharing**: Agents store and retrieve information from shared memory -4. **Result Collection**: Results from all agents are aggregated and presented -## Conclusion +## Best Practices -Multi-agent swarms solve complex problems through collective intelligence. The Strands Agents SDK supports both custom implementations and a built-in swarm tool with shared memory. By distributing tasks across specialized agents and enabling effective communication, swarms achieve better results than single agents working alone. Whether using mesh communication patterns or the swarm tool, developers can create systems where multiple agents work together with defined roles, coordination mechanisms, and knowledge sharing. +1. **Create specialized agents**: Define clear roles for each agent in your Swarm +2. **Use descriptive agent names**: Names should reflect the agent's specialty +3. **Set appropriate timeouts**: Adjust based on task complexity and expected runtime +4. **Enable repetitive handoff detection**: Set appropriate values for `repetitive_handoff_detection_window` and `repetitive_handoff_min_unique_agents` to prevent ping-pong behavior +5. **Include diverse expertise**: Ensure your Swarm has agents with complementary skills +6. **Provide agent descriptions**: Add descriptions to your agents to help other agents understand their capabilities +7. **Leverage multi-modal inputs**: Use ContentBlocks for rich inputs including images