# 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
```python
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
```python
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
```python
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
```python
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**:
   ```python
   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:

```python
# 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"