144 lines
6.1 KiB
Markdown
144 lines
6.1 KiB
Markdown
# Understanding Multi-Agent Transfers
|
||
|
||
## What "Successfully transferred..." means
|
||
|
||
When you see messages like:
|
||
- `Successfully transferred to system_info_worker`
|
||
- `Successfully transferred back to supervisor`
|
||
|
||
These are **tool execution results** from the LangGraph supervisor pattern. Here's what's happening:
|
||
|
||
## 🔄 The Transfer Flow
|
||
|
||
1. **Supervisor receives user query**: "Nginx returns 502 Bad Gateway on my server. What can I do?"
|
||
|
||
2. **Supervisor analyzes and delegates**: Based on the `SUPERVISOR_PROMPT` in `config.py`, it decides to start with `system_info_worker`
|
||
|
||
3. **Transfer tool execution**: Supervisor calls `transfer_to_system_info_worker` tool
|
||
- **Result**: "Successfully transferred to system_info_worker"
|
||
- **Meaning**: Control is now handed to the system_info_worker agent
|
||
|
||
4. **Agent executes**: The `system_info_worker` gets:
|
||
- Full conversation context (including the original user query)
|
||
- Its own specialized prompt from `agents/system_agents.py`
|
||
- Access to its tools (shell commands for system info)
|
||
|
||
5. **Agent completes and returns**: Agent calls `transfer_back_to_supervisor`
|
||
- **Result**: "Successfully transferred back to supervisor"
|
||
- **Meaning**: Agent finished its task and returned control
|
||
- **Important**: Agent's results are now part of the conversation history
|
||
|
||
6. **Supervisor decides next step**: Based on **accumulated results**, supervisor either:
|
||
- Delegates to another agent (e.g., `service_inventory_worker`)
|
||
- Provides final response to user
|
||
- **Key**: Supervisor can see ALL previous agent results when making decisions
|
||
|
||
## 🧠 How Prompts Work
|
||
|
||
### Supervisor Prompt (config.py)
|
||
```python
|
||
SUPERVISOR_PROMPT = """
|
||
You are the supervisor of a team of specialised sysadmin agents.
|
||
Decide which agent to delegate to based on the user's query **or** on results already collected.
|
||
Available agents:
|
||
- system_info_worker: gather system metrics
|
||
- service_inventory_worker: list running services
|
||
- mariadb_analyzer: analyse MariaDB
|
||
...
|
||
Always start with `system_info_worker` and `service_inventory_worker` before drilling into a specific service.
|
||
"""
|
||
```
|
||
|
||
### Agent Prompts (agents/*.py)
|
||
Each agent has its own specialized prompt, for example:
|
||
|
||
```python
|
||
# system_info_worker prompt
|
||
"""
|
||
You are a Linux sysadmin. Use shell commands like `lscpu`, `free -h`, and `df -h` to gather CPU, RAM, and disk usage.
|
||
Return a concise plain‑text summary. Only run safe, read‑only commands.
|
||
"""
|
||
```
|
||
|
||
## 🎯 What Each Agent Receives
|
||
|
||
When an agent is activated via transfer:
|
||
- **Full conversation history**: All previous messages between user, supervisor, and other agents
|
||
- **Specialized prompt**: Guides how the agent should interpret and act on the conversation
|
||
- **Tools**: Shell access, specific analyzers, etc.
|
||
- **Context**: Results from previous agents in the conversation
|
||
|
||
## 🔄 How Agent Results Flow Back to Supervisor
|
||
|
||
**This is the key mechanism that makes the multi-agent system intelligent:**
|
||
|
||
1. **Agent produces results**: Each agent generates an `AIMessage` with its findings/analysis
|
||
2. **Results become part of conversation**: The agent's response is added to the shared message history
|
||
3. **Supervisor sees everything**: When control returns to supervisor, it has access to:
|
||
- Original user query
|
||
- All previous agent responses
|
||
- Tool execution results
|
||
- Complete conversation context
|
||
|
||
4. **Supervisor strategy updates**: Based on accumulated knowledge, supervisor can:
|
||
- Decide which agent to call next
|
||
- Skip unnecessary agents if enough info is gathered
|
||
- Synthesize results from multiple agents
|
||
- Provide final comprehensive response
|
||
|
||
### Example Flow:
|
||
```
|
||
User: "Nginx 502 error, help!"
|
||
├── Supervisor → system_info_worker
|
||
│ └── Returns: "502 usually means upstream server issues, check logs..."
|
||
├── Supervisor (now knows about upstream issues) → service_inventory_worker
|
||
│ └── Returns: "Check PHP-FPM status, verify upstream config..."
|
||
└── Supervisor (has both perspectives) → Final synthesis
|
||
└── "Based on system analysis and service inventory, here's comprehensive solution..."
|
||
```
|
||
|
||
## 🔍 Enhanced Debugging
|
||
|
||
The updated `utils.py` now shows:
|
||
- **Transfer explanations**: What each "Successfully transferred" means
|
||
- **Conversation context**: Last few messages to understand the flow
|
||
- **Tool call details**: What tools are being used and why
|
||
- **Agent delegation**: Which agent is being called and for what purpose
|
||
|
||
## 🔍 Observing Result Flow in Practice
|
||
|
||
To see how results flow back to the supervisor, run the enhanced debugging and watch for:
|
||
|
||
1. **Agent Results**: Look for `AIMessage` from agents (not just transfer confirmations)
|
||
2. **Conversation Context**: The expanding message history in each step
|
||
3. **Supervisor Decision Changes**: How supervisor's next choice is influenced by results
|
||
|
||
### Example Debug Output Analysis:
|
||
```
|
||
🔄 STEP 2: system_info_worker
|
||
💬 MESSAGE TYPE: AIMessage ← AGENT'S ACTUAL RESULT
|
||
📄 CONTENT: "502 typically indicates upstream server issues..."
|
||
|
||
🔄 STEP 4: service_inventory_worker
|
||
💬 MESSAGE TYPE: AIMessage ← AGENT'S ACTUAL RESULT
|
||
📄 CONTENT: "Check PHP-FPM status, verify upstream config..."
|
||
|
||
🔄 STEP 5: supervisor
|
||
💬 MESSAGE TYPE: AIMessage ← SUPERVISOR'S SYNTHESIS
|
||
📄 CONTENT: "Based on system analysis and service inventory..."
|
||
📚 CONVERSATION CONTEXT (12 messages) ← SUPERVISOR SEES ALL RESULTS
|
||
```
|
||
|
||
The supervisor's final response demonstrates it has processed and synthesized results from both agents!
|
||
|
||
## 📋 Key Takeaways
|
||
|
||
- **"Successfully transferred"** = Control handoff confirmation, not data transfer
|
||
- **Each agent** gets the full conversation context INCLUDING previous agent results
|
||
- **Agent prompts** determine how they process that context
|
||
- **Supervisor** orchestrates the workflow based on its prompt strategy
|
||
- **The conversation** builds up context as each agent contributes their expertise
|
||
- **Results accumulate**: Each agent can see and build upon previous agents' work
|
||
- **Supervisor learns**: Strategy updates based on what agents discover
|
||
- **Dynamic workflow**: Supervisor can skip agents or change direction based on results
|