claude_swarm 1.0.5 → 1.0.7

data/docs/v2/guides/getting-started.md

@@ -139,6 +139,47 @@ Delegation is how agents collaborate. When an agent is configured with `delegate
 
 Delegation creates flexible collaboration patterns without rigid workflows.
 
+#### Delegation Isolation Modes
+
+When multiple agents delegate to the same target, you can control whether they share the same conversation history or get isolated instances:
+
+**Isolated Mode (Default - Recommended):**
+```yaml
+agents:
+  tester:
+    description: "Testing agent"
+    # shared_across_delegations: false (default)
+
+  frontend:
+    delegates_to: [tester]  # Gets tester@frontend (isolated)
+
+  backend:
+    delegates_to: [tester]  # Gets tester@backend (separate)
+```
+
+Each delegator gets its own isolated instance with separate conversation history. This prevents context mixing and ensures clean boundaries.
+
+**Shared Mode (Opt-in):**
+```yaml
+agents:
+  database:
+    description: "Database coordination agent"
+    shared_across_delegations: true
+
+  frontend:
+    delegates_to: [database]  # Shares same database instance
+
+  backend:
+    delegates_to: [database]  # Shares same database instance
+```
+
+All delegators share the same agent instance and conversation history. Use this for stateful coordination or when context sharing is beneficial.
+
+**Key Points:**
+- **Memory is always shared**: SwarmMemory and other plugin storage is shared by base agent name across all instances
+- **Only conversation history differs**: Isolated mode separates conversations, but knowledge is shared
+- **Choose based on use case**: Use isolated (default) for independent tasks, shared for coordination
+
 ### Tools
 
 Tools are functions agents call to interact with the world. SwarmSDK provides:
@@ -154,7 +195,7 @@ Tools are functions agents call to interact with the world. SwarmSDK provides:
 | **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
 | **Reasoning** | Think | Extended reasoning for complex problems |
 
-**Default tools**: Every agent automatically gets Read, Grep, Glob, TodoWrite, Think, WebFetch, and scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) unless you explicitly disable them with `disable_default_tools: true`.
+**Default tools**: Every agent automatically gets **Read, Grep, and Glob** unless you explicitly disable them with `disable_default_tools: true`. Scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) are opt-in via `scratchpad: :enabled`.
 
 **Memory tools** are opt-in for learning agents that need persistent knowledge storage.
 
@@ -303,7 +344,7 @@ agents:
 require 'swarm_sdk'
 
 # Load swarm from YAML (which references the Markdown file)
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 result = swarm.execute("Your task here")
 ```
 
@@ -359,7 +400,7 @@ Create a file called `run.rb`:
 require 'swarm_sdk'
 
 # Load swarm from YAML
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 
 # Execute a task
 result = swarm.execute("What is 2 + 2?")
@@ -433,7 +474,7 @@ Create `run.rb`:
 require 'swarm_sdk'
 
 # Load swarm from YAML (which references the Markdown file)
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 
 # Execute a task
 result = swarm.execute("What is 2 + 2?")
@@ -705,7 +746,7 @@ swarm:
 
 Then load and use:
 ```ruby
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 result = swarm.execute("Write a function to validate email addresses and get it reviewed")
 ```
 
@@ -1292,7 +1333,7 @@ swarm:
 ```ruby
 # run.rb
 require 'swarm_sdk'
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 result = swarm.execute("Your task here")
 puts result.content if result.success?
 ```
@@ -1327,7 +1368,7 @@ swarm:
 ```ruby
 # run.rb
 require 'swarm_sdk'
-swarm = SwarmSDK::Swarm.load('swarm.yml')
+swarm = SwarmSDK.load_file('swarm.yml')
 result = swarm.execute("Your task here")
 ```