Skip to content

Architecture

The Bedrock Swarm uses a coordinator-based architecture to manage communication between specialized agents. This design allows for complex tasks to be broken down into smaller steps and executed by the most appropriate specialists.

Core Components

Agency

The central orchestrator that: - Manages communication between agents - Creates and maintains the coordinator agent - Handles request processing and plan execution - Manages shared memory and event tracing

Coordinator

A specialized agent that: - Receives user requests - Creates structured execution plans - Delegates tasks to appropriate specialists - Formats final responses

Specialists

Domain-specific agents that: - Handle specific types of tasks (e.g., calculations, time operations) - Execute tools within their domain - Return results to the coordinator

Communication Flow

sequenceDiagram
    participant User
    participant Agency
    participant Coordinator
    participant Calculator
    participant TimeExpert

    User->>Agency: process_request("What time will it be 15 * 7 minutes from now?")
    Agency->>Coordinator: create_plan(request)

    Note over Coordinator: Creates structured plan<br/>with calculation and time steps

    Coordinator-->>Agency: Returns validated plan

    Agency->>Calculator: execute_step("Calculate 15 * 7")
    Calculator-->>Agency: "105"

    Agency->>TimeExpert: execute_step("Calculate time 105 minutes from now")
    TimeExpert-->>Agency: "8:19 PM UTC"

    Agency->>Coordinator: format_response(results)
    Coordinator-->>Agency: Formatted natural response
    Agency-->>User: "In 105 minutes, it will be 8:19 PM UTC"

Request Processing Flow

  1. Plan Creation Phase
  2. User sends request to Agency
  3. Agency forwards to Coordinator
  4. Coordinator creates structured plan using create_plan tool

  5. Plan is validated and stored

  6. Execution Phase

  7. Agency executes each step in sequence
  8. Specialists are called with their specific tasks
  9. Results are collected and dependencies managed

  10. Events are traced for debugging

  11. Response Formatting Phase

  12. Results are sent back to Coordinator
  13. Coordinator formats natural response
  14. Final response returned to user

Example Plan Structure

{
  "steps": [
    {
      "step_number": 1,
      "description": "Calculate 15 * 7",
      "specialist": "calculator"
    },
    {
      "step_number": 2,
      "description": "Calculate the time {MINUTES} minutes from now",
      "specialist": "time_expert",
      "requires_results_from": [1]
    }
  ],
  "final_output_format": "In {MINUTES} minutes, the time will be {TIME}"
}

Event Tracing

The Agency includes comprehensive event tracing to help debug and monitor the execution flow:

[timestamp] run_start - Agent: coordinator
[timestamp] tool_start - Agent: coordinator
[timestamp] tool_complete - Agent: coordinator
[timestamp] execution_start - Agent: agency
[timestamp] step_complete - Agent: calculator
[timestamp] step_complete - Agent: time_expert
[timestamp] execution_complete - Agent: agency
[timestamp] response_complete - Agent: agency

Best Practices

  1. Specialist Design
  2. Keep specialists focused on a single domain
  3. Provide clear tool descriptions

  4. Handle errors gracefully

  5. Plan Creation

  6. Break complex tasks into atomic steps
  7. Specify clear dependencies

  8. Use descriptive step descriptions

  9. Tool Implementation

  10. Validate inputs thoroughly
  11. Return clear, structured outputs
  12. Include helpful error messages