PR feedback

Author: awsarron

docs/user-guide/concepts/multi-agent/graph.md

@@ -1,6 +1,6 @@
 # Graph Multi-Agent Pattern
 
-A Graph is a deterministic Directed Acyclic Graph (DAG) based agent orchestration system where agents or other multi-agent systems (like Swarm 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.
+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
@@ -27,9 +27,39 @@ graph TD
     C --> D
 ```
 
+## Graph Components
+
+### 1. GraphNode
+
+A [`GraphNode`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphNode) represents a node in the graph with:
+
+- **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
+
+### 2. GraphEdge
+
+A [`GraphEdge`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphEdge) represents a connection between nodes with:
+
+- **from_node**: Source node
+- **to_node**: Target node
+- **condition**: Optional function that determines if the edge should be traversed
+
+### 3. GraphBuilder
+
+The [`GraphBuilder`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphBuilder) provides a simple interface for constructing graphs:
+
+- **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
+
 ## Creating a Graph
 
-To create a Graph, you use the `GraphBuilder` to define nodes, edges, and entry points:
+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
@@ -70,36 +100,6 @@ print(f"\nStatus: {result.status}")
 print(f"Execution order: {[node.node_id for node in result.execution_order]}")
 ```
 
-## Graph Components
-
-### 1. GraphNode
-
-A `GraphNode` represents a node in the graph with:
-
-- **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
-
-### 2. GraphEdge
-
-A `GraphEdge` represents a connection between nodes with:
-
-- **from_node**: Source node
-- **to_node**: Target node
-- **condition**: Optional function that determines if the edge should be traversed
-
-### 3. GraphBuilder
-
-The `GraphBuilder` provides a simple interface for constructing graphs:
-
-- **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
-
 ## Conditional Edges
 
 You can add conditional logic to edges to create dynamic workflows:
@@ -121,7 +121,7 @@ builder.add_edge("research", "analysis", condition=only_if_research_successful)
 
 ## Nested Multi-Agent Patterns
 
-You can use a Graph or Swarm as a node within another Graph:
+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:
 
 ```python
 from strands import Agent
@@ -154,7 +154,7 @@ print(f"\n{result}")
 
 ## Multi-Modal Input Support
 
-Graphs support multi-modal inputs like text and images using ContentBlocks:
+Graphs support multi-modal inputs like text and images using [`ContentBlocks`](../../../api-reference/types.md#strands.types.content.ContentBlock):
 
 ```python
 from strands import Agent
@@ -186,21 +186,21 @@ result = graph(content_blocks)
 
 ## Asynchronous Execution
 
-You can also execute a Graph asynchronously:
+You can also execute a Graph asynchronously by calling the [`invoke_async`](../../../api-reference/multiagent.md#strands.multiagent.graph.Graph.invoke_async) function:
 
 ```python
 import asyncio
 
 async def run_graph():
-    result = await graph.execute_async("Research and analyze market trends...")
+    result = await graph.invoke_async("Research and analyze market trends...")
     return result
 
 result = asyncio.run(run_graph())
 ```
 
 ## Graph Results
 
-When a Graph completes execution, it returns a `GraphResult` object with detailed information:
+When a Graph completes execution, it returns a [`GraphResult`](../../../api-reference/multiagent.md#strands.multiagent.graph.GraphResult) object with detailed information:
 
 ```python
 result = graph("Research and analyze...")
@@ -256,9 +256,9 @@ Agents can dynamically create and orchestrate graphs by using the `graph` tool a
 
 ```python
 from strands import Agent
-from strands_tools import graph
+from strands_tools import agent_graph
 
-agent = Agent(tools=[graph], system_prompt="Create a graph of agents to solve the user's query.")
+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")
 ```

docs/user-guide/concepts/multi-agent/swarm.md

@@ -50,7 +50,7 @@ swarm = Swarm(
     max_iterations=20,
     execution_timeout=900.0,  # 15 minutes
     node_timeout=300.0,       # 5 minutes per agent
-    repetitive_handoff_detection_window=8,
+    repetitive_handoff_detection_window=8,  # There must be >= 3 unique agents in the last 8 handoffs
     repetitive_handoff_min_unique_agents=3
 )
 
@@ -73,7 +73,7 @@ In this example:
 
 ## Swarm Configuration
 
-The `Swarm` constructor allows you to control the behavior and safety parameters:
+The [`Swarm`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm) constructor allows you to control the behavior and safety parameters:
 
 | Parameter | Description | Default |
 |-----------|-------------|---------|
@@ -86,7 +86,7 @@ The `Swarm` constructor allows you to control the behavior and safety parameters
 
 ## Multi-Modal Input Support
 
-Swarms support multi-modal inputs like text and images using ContentBlocks:
+Swarms support multi-modal inputs like text and images using [`ContentBlocks`](../../../api-reference/types.md#strands.types.content.ContentBlock):
 
 ```python
 from strands import Agent
@@ -166,21 +166,21 @@ You have access to swarm coordination tools if you need help from other agents o
 
 ## Asynchronous Execution
 
-You can also execute a Swarm asynchronously:
+You can also execute a Swarm asynchronously by calling the [`invoke_async`](../../../api-reference/multiagent.md#strands.multiagent.swarm.Swarm.invoke_async) function:
 
 ```python
 import asyncio
 
 async def run_swarm():
-    result = await swarm.execute_async("Design and implement a complex system...")
+    result = await swarm.invoke_async("Design and implement a complex system...")
     return result
 
 result = asyncio.run(run_swarm())
 ```
 
 ## Swarm Results
 
-When a Swarm completes execution, it returns a `SwarmResult` object with detailed information:
+When a Swarm completes execution, it returns a [`SwarmResult`](../../../api-reference/multiagent.md#strands.multiagent.swarm.SwarmResult) object with detailed information:
 
 ```python
 result = swarm("Design a system architecture for...")
@@ -205,6 +205,26 @@ print(f"Execution time: {result.execution_time}ms")
 print(f"Token usage: {result.accumulated_usage}")
 ```
 
+## Swarm as a 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
+
+agent = Agent(tools=[swarm], system_prompt="Create a swarm of agents to solve the user's query.")
+
+agent("Research, analyze, and summarize the latest advancements in quantum computing")
+```
+
+In this example:
+
+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
+
 ## Safety Mechanisms
 
 Swarms include several safety mechanisms to prevent infinite loops and ensure reliable execution: