Document on parallel agents (#337)

Document on parallel

Co-authored-by: Maria <maria@aliasrobotics.com>

docs/multi_agent.md

@@ -26,4 +26,135 @@ While orchestrating via LLM is powerful, orchestrating via code makes tasks more
 
 - Using [Guardrails](guardrails.md) and LLM_as_judge: They are agents that evaluates and provides feedback, until they says the inputs/outputs passes certain criteria. The agent ensures inputs/outputs are appropriate.
 
-- Paralelization of task: Running multiple agents in parallel. This is useful for speed when you have multiple tasks that don't depend on each other.
+- Paralelization of task: Running multiple agents in parallel. This is useful for speed when you have multiple tasks.
+
+## Running Agents in Parallel
+
+When you have multiple tasks, you can run agents in parallel to improve performance and reduce overall execution time. This is particularly useful in security workflows where you need to perform multiple reconnaissance or analysis tasks simultaneously.
+
+You have two options:
+
+1. **Use built-in parallel patterns** (available via `/agent list`)
+2. **Create your own custom pattern** using `agents.yml` configuration
+
+### Option 1: Using Built-in Parallel Patterns
+
+CAI includes ready-to-use parallel patterns that you can select directly from the CLI.
+
+**View available patterns:**
+
+```bash
+# Launch CAI and list all available patterns
+cai
+CAI> /agent list
+```
+
+**Available parallel patterns:**
+
+| Pattern Name | Agents | Context | Description |
+|--------------|--------|---------|-------------|
+| **offsec_pattern** | redteam_agent + bug_bounter_agent | Split | Bug bounty and red team with different contexts for offensive security ops |
+| **blue_team_red_team_shared_context** | redteam_agent + blueteam_agent | Shared | Red and blue team agents sharing the same message history |
+| **blue_team_red_team_split_context** | redteam_agent + blueteam_agent | Split | Red and blue team agents with separate contexts for independent analysis |
+| **purple_team_gctr** ⭐ | redteam_agent + blueteam_agent (enhanced with G-CTR) | Shared | Combines red and blue team agents with shared GCTR tracking for unified game-theoretic analysis (⭐ this is a [CAI PRO](https://aliasrobotics.com/cybersecurityai.php) capability)|
+
+**To use a pattern:**
+
+```bash
+# Start CAI and select a pattern
+cai
+
+# List available patterns
+CAI> /agent list
+
+# Select a parallel pattern by number or name
+CAI> /agent 23
+# or
+CAI> /agent offsec_pattern
+
+# Now enter your prompt and both agents will work in parallel
+CAI> Analyze https://example.com for vulnerabilities
+```
+
+**How parallel patterns work:**
+
+- **Split context**: Each agent has its own message history and works independently
+- **Shared context**: Both agents see the same message history and can build on each other's work
+
+**Example workflow with offsec_pattern:**
+
+```bash
+CAI> /agent offsec_pattern
+CAI> Find vulnerabilities in https://target.com
+
+# Both redteam_agent and bug_bounter_agent will analyze the target
+# Each provides their perspective (red team exploitation vs bug bounty)
+# You get results from both agents in parallel
+```
+
+### Option 2: Create Your Own Pattern with agents.yml
+
+For a simpler approach, use the `agents.yml` configuration file to run multiple agents in parallel without writing Python code.
+
+**1. Copy the example configuration:**
+
+```bash
+cp agents.yml.example agents.yml
+```
+
+**2. Configure your parallel agents in `agents.yml`:**
+
+
+**Example with unified context:**
+```yaml
+parallel_agents:
+  # Define 2 or more agents to run in parallel
+  - name: one_tool_agent
+    model: alias1
+    prompt: "Focus on finding vulnerabilities"
+    unified_context: false  # Each agent has its own message history
+
+  - name: blueteam_agent
+    model: alias1
+    prompt: "Focus on defensive security"
+    unified_context: false
+```
+
+**Example with Shared context:**
+
+```yaml
+parallel_agents:
+
+  - name: redteam_agent
+    unified_context: true  # Agents share message history
+
+  - name: blueteam_agent
+    unified_context: true  # Can see what redteam agent did
+```
+
+**3. Launch CAI:**
+
+```bash
+# Auto-loads agents.yml from current directory
+cai
+
+# Or load a different configuration file
+cai --yaml agent_custom.yml
+
+# Or specify a full path
+cai --yaml /path/to/my_agents.yml
+```
+
+**How it works:**
+
+- When 2 or more agents are configured, parallel mode is automatically enabled
+- The agents will be available for selection when you enter a prompt
+- Each agent can have its own model, prompt, and context settings
+
+**Configuration options:**
+
+- `name`: The agent type (e.g., `redteam_agent`, `bug_bounter_agent`)
+- `model`: Optional model override (e.g., `alias1`, `alias0`)
+- `prompt`: Optional additional instructions for the agent
+- `unified_context`: Set to `true` to share message history between agents (default: `false`)
+