agent-pard0x/multi-agent-supervisor/docs/DYNAMIC_INSTRUCTIONS.md

Dynamic Instructions for Agent Transfers - TODO

Current Behavior

Currently, when the supervisor transfers control to an agent:

• ❌ No specific instructions are passed
• ❌ Agent only sees the original user query
• ❌ Agent uses its static, pre-defined prompt

Proposed Enhancement: Dynamic Instructions

Why It Matters

The supervisor often has context about WHY it's transferring to a specific agent. For example:

• "Transfer to network_diag because user mentioned DNS issues - focus on DNS diagnostics"
• "Transfer to cert_checker because certificates might be expiring - check all certs urgently"

Implementation Approach

1. Modify Transfer Tools

def transfer_to_network_diag(instructions: str = "") -> str:
    """Transfer control to network diagnostics agent.
    
    Args:
        instructions: Specific guidance for the agent
    """
    return f"Successfully transferred to network_diag. Instructions: {instructions}"

2. Update State to Include Instructions

class State(BaseModel):
    messages: List[AnyMessage]
    next_agent: str = "supervisor"
    supervisor_instructions: Optional[str] = None  # NEW FIELD

3. Modify Agent Creation to Check for Instructions

def create_network_worker():
    return create_react_agent(
        model="openai:gpt-4o-mini",
        tools=[get_shell_tool()],
        prompt="""
{base_prompt}

SUPERVISOR INSTRUCTIONS (if any): {supervisor_instructions}

Always prioritize supervisor instructions when provided.
""",
        name="network_diag"
    )

4. Update Router Logic

def route_agent(state):
    # Extract supervisor instructions from last ToolMessage
    last_message = state["messages"][-1]
    if isinstance(last_message, ToolMessage) and "Instructions:" in last_message.content:
        # Parse and store instructions
        instructions = extract_instructions(last_message.content)
        state["supervisor_instructions"] = instructions
    
    return state["next_agent"]

Example Flow

1. User Query: "My website is slow"

2. Supervisor Analysis:

   "Website slowness could be DNS or certificate related. 
    Let me transfer to network_diag with specific focus."
   

3. Supervisor Transfer:

   transfer_to_network_diag(
       instructions="Focus on DNS resolution times and latency to common websites. 
                     Check if DNS servers are responding slowly."
   )
   

4. Network Agent Receives:

   • Original query: "My website is slow"
   • Supervisor instructions: "Focus on DNS resolution times..."
   • Can now prioritize DNS diagnostics over general network checks

Benefits

1. More Targeted Diagnostics: Agents focus on what matters
2. Better Context Sharing: Supervisor's analysis isn't lost
3. Efficient Execution: Avoid running unnecessary commands
4. Improved Results: More relevant output for user's specific issue

Alternative: Context in Messages

Instead of modifying tools, append supervisor analysis to the message history:

# Before transfer, supervisor adds a system message
state["messages"].append(
    SystemMessage(content=f"[SUPERVISOR GUIDANCE]: Focus on {specific_issue}")
)

Decision Points

1. Tool Parameters vs State: Where to store instructions?
2. Prompt Injection vs Message History: How to pass instructions?
3. Optional vs Required: Should all transfers include instructions?
4. Persistence: Should instructions carry through multiple agent hops?

Next Steps

1. Decide on implementation approach
2. Modify transfer tool signatures
3. Update state model
4. Enhance agent prompts to use instructions
5. Test with various scenarios
6. Document the new pattern

Example Test Cases

• "Check network" → No specific instructions needed
• "Website is slow" → "Focus on DNS and latency"
• "Certificate expiring?" → "Check all certs, prioritize those expiring soon"
• "Port 443 issues" → "Focus on HTTPS connectivity and certificate validation"