Multi-Agent Orchestrator Blueprint

You are a task orchestrator. Your job is to decompose complex tasks and delegate
subtasks to specialized workers. You manage three workers:

- RESEARCHER: Searches and synthesizes information. Provides factual, cited answers.
- CODER: Writes and explains Python code. Produces working, documented scripts.
- WRITER: Produces polished prose — summaries, reports, articles, documentation.

Follow this protocol:
1. THOUGHT: What does the user need? Which workers are required? In what order?
2. PLAN: Decompose the task into subtasks, each assigned to a specific worker
3. DELEGATE: Send each subtask to the appropriate worker, one at a time
4. AGGREGATE: Combine worker outputs into a cohesive final result
5. FINAL_OUTPUT: The complete, integrated answer to the user's request

Rules:
- Delegate subtasks sequentially when outputs depend on each other (research → code → write)
- Delegate in parallel when subtasks are independent
- Pass relevant context from earlier workers to later workers
- If a worker produces low-quality output, re-delegate with more specific instructions
- The final output should read as one cohesive piece, not three separate sections

### Worker Definitions

```python
# workers.py
import json

WORKER_SYSTEM_PROMPTS = {
    "researcher": """You are a research specialist. Your job is to gather and synthesize
information on a given topic. Provide factual, well-organized answers with specific
data points where available. Cite your sources when possible.

Rules:
- Be thorough — cover multiple angles of the topic
- Use specific numbers and data, not vague claims
- Organize findings with clear headings
- If information is uncertain, note the uncertainty""",

    "coder": """You are a Python programmer. Your job is to write clean, documented,
working Python code that solves the given problem. Include comments explaining
key decisions.

Rules:
- Write complete, runnable scripts — no placeholders or TODOs
- Include type hints and docstrings
- Handle edge cases and errors gracefully
- Add a brief explanation of how the code works
- Use only standard library or widely-available packages""",

    "writer": """You are a professional writer and editor. Your job is to produce
polished, clear, and engaging prose from the provided information.

Rules:
- Adapt your tone to the audience and purpose specified
- Structure content with clear headings and logical flow
- Be concise — cut unnecessary words
- Maintain a consistent voice throughout
- If source material has gaps, note them rather than fabricating"""
}


def run_worker(client, model, worker_name, task, temperature=0.3):
    """Run a single worker on a task and return its output."""
    system_prompt = WORKER_SYSTEM_PROMPTS.get(worker_name)
    if not system_prompt:
        return f"ERROR: Unknown worker: {worker_name}. Available: {list(WORKER_SYSTEM_PROMPTS.keys())}"

    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": task}
    ]

    response = client.chat.completions.create(
        model=model,
        messages=messages,
        temperature=temperature
    )

    return response.choices[0].message.content

# tools.py (embedded in orchestrator.py for simplicity in this blueprint)
import json

def delegate_to(client, model, worker_name, task, temperature):
    """Delegate a task to a worker and return the result."""
    from workers import run_worker
    output = run_worker(client, model, worker_name, task, temperature)
    return json.dumps({
        "worker": worker_name,
        "task": task,
        "output": output
    }, indent=2)


def aggregate_results(client, model, original_task, worker_outputs):
    """Synthesize worker outputs into a cohesive final result."""
    outputs_text = "\n\n---\n\n".join(
        f"Worker: {w.get('worker', 'unknown')}\nTask: {w.get('task', '')}\nOutput: {w.get('output', '')}"
        for w in worker_outputs
    )

    prompt = f"""Synthesize the following worker outputs into one cohesive response
for the original task. The final output should read as a single piece, not separate
sections from different workers.

Original task: {original_task}

Worker outputs:
{outputs_text}

Combine these into a unified, well-structured answer. Use the writer's output as
the narrative backbone, and integrate the researcher's facts and coder's script
where appropriate."""

    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.2
    )
    return response.choices[0].message.content

# orchestrator.py
import json
import argparse
from openai import OpenAI
import workers
import tools

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "delegate_to",
            "description": "Delegate a subtask to a specialized worker: researcher, coder, or writer",
            "parameters": {
                "type": "object",
                "properties": {
                    "worker_name": {"type": "string", "enum": ["researcher", "coder", "writer"]},
                    "task": {"type": "string", "description": "The subtask for the worker to complete"}
                },
                "required": ["worker_name", "task"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "aggregate_results",
            "description": "Synthesize outputs from multiple workers into a cohesive final result",
            "parameters": {
                "type": "object",
                "properties": {
                    "task": {"type": "string", "description": "The original user task"},
                    "worker_outputs": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "worker": {"type": "string"},
                                "task": {"type": "string"},
                                "output": {"type": "string"}
                            }
                        }
                    }
                },
                "required": ["task", "worker_outputs"]
            }
        }
    }
]

SYSTEM_PROMPT = """You are a task orchestrator. You manage three specialized workers:
- RESEARCHER: Searches and synthesizes information. Provides factual, cited answers.
- CODER: Writes and explains Python code. Produces working, documented scripts.
- WRITER: Produces polished prose — summaries, reports, articles.

Protocol:
1. THOUGHT: What does the user need? Which workers? What order?
2. PLAN: Decompose the task into subtasks for specific workers
3. DELEGATE: Send subtasks to workers sequentially (outputs feed forward) or in parallel
4. AGGREGATE: Combine outputs into a cohesive result
5. FINAL_OUTPUT: The complete answer

Rules:
- Delegate sequentially when outputs depend on earlier results
- Pass relevant context when delegating to later workers
- If a worker output is poor, re-delegate with clearer instructions
- The final output must read as one cohesive piece"""


def run_orchestrator(task: str, config: dict):
    client = OpenAI(api_key=config["openai_api_key"])
    model = config.get("model", "gpt-4o")
    worker_temp = config.get("worker_temperature", 0.3)
    verbose = config.get("verbose", True)

    worker_outputs = []

    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": f"Complete this task: {task}"}
    ]

    for i in range(config.get("max_iterations", 10)):
        response = client.chat.completions.create(
            model=model,
            messages=messages,
            tools=TOOL_SCHEMAS,
            temperature=0.2
        )

        msg = response.choices[0].message
        messages.append(msg)

        if msg.content and "FINAL_OUTPUT:" in msg.content:
            return msg.content.split("FINAL_OUTPUT:", 1)[1].strip()

        if not msg.tool_calls:
            messages.append({
                "role": "user",
                "content": "Continue. Delegate subtasks to workers, then aggregate results. End with FINAL_OUTPUT."
            })
            continue

        for tool_call in msg.tool_calls:
            func_name = tool_call.function.name
            func_args = json.loads(tool_call.function.arguments)

            if func_name == "delegate_to":
                worker_name = func_args.get("worker_name")
                worker_task = func_args.get("task", "")
                if verbose:
                    print(f"\n  → Delegating to {worker_name}: {worker_task[:80]}...")
                result = tools.delegate_to(
                    client, model, worker_name, worker_task, worker_temp)
                worker_outputs.append({
                    "worker": worker_name,
                    "task": worker_task,
                    "output": result
                })

            elif func_name == "aggregate_results":
                result = tools.aggregate_results(
                    client, model,
                    func_args.get("task", task),
                    func_args.get("worker_outputs", worker_outputs))

            else:
                result = f"Unknown tool: {func_name}"

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": result
            })

    return "Orchestrator reached max iterations."


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--task", required=True, help="Complex task to decompose and delegate")
    parser.add_argument("--config", default="config.json")
    args = parser.parse_args()

    with open(args.config) as f:
        config = json.load(f)

    result = run_orchestrator(args.task, config)
    print("\n" + "=" * 60)
    print(result)