Coordination Patterns#

Source: examples/patterns/coordination_patterns.py

Introduction#

Blackboard-system architecture motivates shared-state collaboration among specialized problem solvers, AutoGen informs practical multi-agent implementation choices, and Human-AI collaboration by design clarifies governance value in shared workspace reasoning. This example compares round-based coordination and blackboard-specialized runs with explicit execution records.

Technical Implementation#

  1. Configure Tracer with JSONL + console output so each run emits machine-readable traces and lifecycle logs.

  2. Build the runtime surface (public APIs only) and execute RoundBasedCoordinationPattern.run(...) with a fixed request_id.

  3. Capture structured outputs from runtime execution and preserve termination metadata for analysis.

  4. Print a compact JSON payload including trace_info for deterministic tests and docs examples.

        flowchart LR
    A["Input prompt or scenario"] --> B["main(): runtime wiring"]
    B --> C["RoundBasedCoordinationPattern.run(...)"]
    C --> D["blackboard workers contribute and aggregate shared state"]
    C --> E["Tracer JSONL + console events"]
    D --> F["ExecutionResult/payload"]
    E --> F
    F --> G["Printed JSON output"]
    
 1from __future__ import annotations
 2
 3import json
 4from pathlib import Path
 5
 6import design_research_agents as drag
 7
 8
 9def _summarize(result: drag.ExecutionResult) -> dict[str, object]:
10    return result.summary()
11
12
13def main() -> None:
14    """Run one round-based coordination and one blackboard pass."""
15    tracer = drag.Tracer(
16        enabled=True,
17        trace_dir=Path("artifacts/examples/traces"),
18        enable_jsonl=True,
19        enable_console=True,
20    )
21
22    with drag.LlamaCppServerLLMClient(context_window=16384) as llm_client:
23        peer_a = drag.DirectLLMCall(llm_client=llm_client, tracer=tracer)
24        peer_b = drag.DirectLLMCall(llm_client=llm_client, tracer=tracer)
25
26        # Split ids by pattern variant to keep networked and blackboard traces distinct.
27
28        coordination_request_id = "example-workflow-round-based-coordination-design-001"
29        coordination = drag.RoundBasedCoordinationPattern(
30            peers={
31                "peer_b": peer_b,
32                "peer_a": peer_a,
33            },
34            max_rounds=1,
35            tracer=tracer,
36        )
37        coordination_result = coordination.run(
38            "Exchange one concise proposal for a field-serviceable sensor enclosure.",
39            request_id=coordination_request_id,
40        )
41
42        # Split ids by pattern variant to keep networked and blackboard traces distinct.
43
44        blackboard_request_id = "example-workflow-blackboard-design-001"
45        blackboard = drag.BlackboardPattern(
46            peers={
47                "peer_b": peer_b,
48                "peer_a": peer_a,
49            },
50            max_rounds=1,
51            stability_rounds=1,
52            tracer=tracer,
53        )
54        blackboard_result = blackboard.run(
55            "Compare two concept options and make one concise serviceability recommendation.",
56            request_id=blackboard_request_id,
57        )
58
59    print(
60        json.dumps(
61            {
62                "blackboard": _summarize(blackboard_result),
63                "round_based_coordination": _summarize(coordination_result),
64            },
65            ensure_ascii=True,
66            indent=2,
67            sort_keys=True,
68        )
69    )
70
71
72if __name__ == "__main__":
73    main()

Expected Results#

Run Command

PYTHONPATH=src python3 examples/patterns/coordination_patterns.py

Example output shape (values vary by run):

{
  "round_based_coordination": {
    "success": true,
    "final_output": "<example-specific payload>",
    "terminated_reason": "<string-or-null>",
    "error": null,
    "trace": {
      "request_id": "<request-id>",
      "trace_dir": "artifacts/examples/traces",
      "trace_path": "artifacts/examples/traces/run_<timestamp>_<request_id>.jsonl"
    }
  },
  "blackboard": {
    "success": true,
    "final_output": "<example-specific payload>",
    "terminated_reason": "<string-or-null>",
    "error": null,
    "trace": {
      "request_id": "<request-id>",
      "trace_dir": "artifacts/examples/traces",
      "trace_path": "artifacts/examples/traces/run_<timestamp>_<request_id>.jsonl"
    }
  }
}

References#