Agent Design Patterns - magicplatforms/ai-workflows GitHub Wiki

Below are copy‑ready Mermaid sequence diagrams that map the key agentic design and architectural patterns you described. Paste any of these fenced blocks directly into a GitHub Wiki page (GitHub renders Mermaid natively).

---

1 · Reflection Pattern

sequenceDiagram
    actor User
    participant Agent
    participant Reflector

    User->>Agent: Task request
    Agent->>Agent: Generate draft
    Agent->>Reflector: Ask for critique
    Reflector-->>Agent: Feedback & issues
    Agent->>Agent: Revise draft
    loop Repeat until quality threshold
        Agent->>Reflector: Re‑evaluate revision
        Reflector-->>Agent: Further feedback
        Agent->>Agent: Improve draft
    end
    Agent-->>User: Final refined output

---

2 · Tool‑Use Pattern (“Toolformer‑style”)

sequenceDiagram
    actor User
    participant Agent
    participant ToolAPI as "External Tool / API"

    User->>Agent: Query or task
    Agent->>Agent: Reason over request
    Agent->>ToolAPI: Invoke tool with parameters
    ToolAPI-->>Agent: Structured result
    Agent->>Agent: Integrate result into answer
    Agent-->>User: Up‑to‑date response / action confirmation

---

3 · ReAct Pattern (Reason ↔ Act Loop)

sequenceDiagram
    actor User
    participant Agent
    participant Tool

    User->>Agent: Complex question or goal
    loop Thought / Action / Observation
        Agent->>Agent: Think step‑by‑step
        alt Needs external info
            Agent->>Tool: Invoke tool
            Tool-->>Agent: Return observation
        else Sufficient info gathered
            Agent->>Agent: Prepare answer
        end
    end
    Agent-->>User: Final answer

---

4 · Planning Pattern (Hierarchical Decomposition)

sequenceDiagram
    actor User
    participant Planner as "Planner Agent"
    participant Worker1 as "Worker Agent A"
    participant Worker2 as "Worker Agent B"
    participant ToolA
    participant ToolB

    User->>Planner: High‑level objective
    Planner->>Planner: Generate ordered task list
    Planner->>Worker1: Sub‑task 1
    Worker1->>ToolA: Execute
    ToolA-->>Worker1: Result 1
    Worker1-->>Planner: Return result 1
    Planner->>Worker2: Sub‑task 2
    Worker2->>ToolB: Execute
    ToolB-->>Worker2: Result 2
    Worker2-->>Planner: Return result 2
    Planner->>Planner: Aggregate / verify
    Planner-->>User: Consolidated deliverable

---

5 · Multi‑Agent Collaboration (“AI Team”)

sequenceDiagram
    actor User
    participant Mediator as "Coordinator Agent"
    participant Researcher as "Researcher Agent"
    participant Writer as "Writer Agent"
    participant Reviewer as "Reviewer Agent"
    participant Search as "Search Tool"

    User->>Mediator: Request full report
    Mediator->>Researcher: Need key facts
    Researcher->>Search: Web / DB queries
    Search-->>Researcher: Source material
    Researcher-->>Mediator: Structured notes
    Mediator->>Writer: Draft report from notes
    Writer-->>Reviewer: Send draft for QA
    Reviewer-->>Writer: Edits & comments
    Writer-->>Mediator: Polished report
    Mediator-->>User: Final approved deliverable

---

6 · Enterprise “Agent‑on‑Rails” Architecture (Runtime Sequence)

sequenceDiagram
    actor Employee as "Business User"
    participant UI as "App UI / Chat"
    participant Orchestrator as "Agent Controller"
    participant LLM as "LLM Kernel"
    participant Policy as "Guardrails / Policy Engine"
    participant ToolBus as "Enterprise APIs / Tools"
    participant Audit as "Observability Logs"

    Employee->>UI: Request (e.g., “Update Salesforce lead”)
    UI->>Orchestrator: Forward request + session context
    Orchestrator->>LLM: Prompt with tools list & memory
    LLM-->>Orchestrator: Proposed action(s) & rationale
    Orchestrator->>Policy: Validate against rules
    alt Allowed
        Policy-->>Orchestrator: ✓
        Orchestrator->>ToolBus: Execute API call
        ToolBus-->>Orchestrator: Success / data
    else Blocked / needs approval
        Policy-->>Orchestrator: ✗  (route to human)
    end
    Orchestrator->>Audit: Log thought, actions, results
    Orchestrator-->>UI: Confirmation / outcome
    UI-->>Employee: “Lead updated successfully.”

---

Usage tips

• Keep each diagram in its own fenced ```mermaid block for best readability.
• GitHub Wiki supports live resize; narrow diagrams by renaming participant labels or collapsing steps if needed.
• For very large flows, consider using Mermaid’s autonumber or opt/alt/loop blocks to reduce visual clutter.

Feel free to tailor participant names or add messages to match the specifics of your report or codebase.