Overview
Large Language Model (LLM) multi-agent systems have become a popular paradigm for tackling complex tasks through collaborative interactions among specialized agents. Despite their promise, these systems frequently encounter task failures—a single misstep, miscommunication, or transmission error can cascade into a complete breakdown. Developers are left sifting through massive interaction logs to answer a critical question: which agent caused the failure, and at what point? This process, often called "manual log archaeology," is time-consuming, error-prone, and heavily reliant on deep system expertise.
To address this, researchers from Penn State University and Duke University, in collaboration with Google DeepMind, the University of Washington, Meta, Nanyang Technological University, and Oregon State University, introduced the novel problem of Automated Failure Attribution. They created the first dedicated benchmark dataset, Who&When, and developed multiple automated attribution methods. Their work was accepted as a Spotlight presentation at ICML 2025, and the code and dataset are fully open-source. This guide walks you through the concepts, tools, and practical steps to implement automated failure attribution in your own multi-agent systems.
Prerequisites
Before diving into the tutorial, ensure you have the following:
- Basic knowledge of LLM multi-agent systems: Understand how agents communicate, plan, and execute tasks.
- Python programming skills: Familiarity with Python 3.8+ and common data science libraries (NumPy, Pandas, PyTorch).
- Access to the Who&When dataset: Download from Hugging Face.
- Git and GitHub: Clone the official repository.
- LLM API or local model: For attribution methods, you may need an LLM (e.g., GPT-4, Llama 3) for evaluation or fine-tuning.
Step-by-Step Instructions
1. Understanding the Who&When Dataset
The dataset consists of interaction logs from multi-agent systems that attempted various tasks. Each log includes:
- Agent IDs and roles: e.g., planner, executor, verifier.
- Temporal sequence of actions: timestamps for each agent's message or action.
- Task outcome: success or failure.
- Ground-truth attribution labels: which agent(s) were responsible for the failure and at which time steps.
Example entry (simplified JSON):
{
"task_id": 42,
"log": [
{"agent": "planner", "time": 1, "content": "Plan: go to location A"},
{"agent": "executor", "time": 2, "content": "Attempting to move..."},
{"agent": "executor", "time": 3, "content": "Error: path blocked"},
{"agent": "verifier", "time": 4, "content": "Sending alert"}
],
"outcome": "failure",
"ground_truth": [{"agent": "executor", "time": 2}]
}
2. Setting Up the Environment
Clone the repository and install dependencies:
git clone https://github.com/mingyin1/Agents_Failure_Attribution.git
cd Agents_Failure_Attribution
pip install -r requirements.txt # includes transformers, datasets, etc.
3. Loading and Exploring the Data
Use the Hugging Face datasets library to load the data:
from datasets import load_dataset
dataset = load_dataset("Kevin355/Who_and_When", split="train")
print(dataset[0]["task_id"], dataset[0]["outcome"])
Check the structure: each entry has fields log, outcome, ground_truth, and metadata. Analyze the distribution of failure causes to understand common patterns.
4. Implementing a Baseline Attribution Method
The simplest approach is to use an LLM as a judge to analyze logs and identify the failing agent and time step. Below is a minimal implementation using the OpenAI API (replace with your API key):
import openai
def llm_attribution(log, model="gpt-4"):
prompt = f"You are analyzing a multi-agent system log. Identify which agent caused the failure and at which time step. Log: {log}. Output format: Agent: , Time: "
response = openai.ChatCompletion.create(model=model, messages=[{"role": "user", "content": prompt}])
return parse_response(response.choices[0].message.content)
Evaluate accuracy against ground truth. The paper also introduces more advanced methods like Flow-Consistency Checking and Temporal Attribution via fine-tuned LMs.
5. Evaluating Attribution Methods
Use the provided evaluation scripts to compute metrics (precision, recall, F1 for agent identification, temporal error):
python evaluate.py --method llm_judge --dataset who_and_when
Compare results with the baselines reported in the paper.
6. Adapting to Your Own Multi-Agent System
To use the attribution framework on your logs, convert them to the Who&When format: each log entry must have agent, time, and content. Then run one of the attribution methods. See the custom_logs/ directory for examples.
Common Mistakes
- Ignoring temporal dependencies: A failure may be caused by an early action that only manifests later. Always consider the entire timeline, not just the last step.
- Over-relying on a single agent's logs: Agents may misreport or omit critical context. Cross-validate with logs from other agents.
- Assuming failures always involve an action error: Sometimes failures are due to inaction (e.g., an agent never responds). Your attribution method should handle omission faults.
- Failing to normalize log formats: Different systems use different schemas. Ensure consistent parsing before feeding into attribution models.
- Not handling multi-cause scenarios: A failure may involve multiple agents at different times. Your method should output multiple responsible entities (the Who&When dataset supports multiple labels).
Summary
Automated failure attribution is a critical capability for debugging and improving LLM multi-agent systems. This guide introduced the Who&When benchmark, walked through data loading and a basic LLM-based attribution method, and highlighted pitfalls to avoid. By adopting these techniques, developers can drastically reduce the manual effort needed to find the root cause of failures, accelerating system iteration. For full details, refer to the original paper and the open-source repository.