ag2tracer 0.1.1

Failure attribution on multi-agent traces

ag2tracer

Failure attribution on multi-agent traces. Given a conversation trace from a multi-agent system, ag2tracer identifies which agent made the decisive error and at which step.

Installation

pip install ag2tracer

Setup

Set at least one API key:

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"   # optional
export GOOGLE_API_KEY="your-google-key"          # optional

Web Interface

# Launch the web UI
ag2tracer launch

# Or run in background
ag2tracer launch --daemon

# Other commands
ag2tracer status    # check if server is running
ag2tracer logs      # view server logs
ag2tracer logs -f   # follow logs
ag2tracer stop      # stop the background server

Then open http://127.0.0.1:8500 to:

1. Upload a trace JSON file (must contain a history field)
2. Browse the conversation with a sliding-window viewer
3. Select an attribution method and click Start
4. View the failure-responsible agent and decisive error step

Python API

import json
from ag2tracer import all_at_once, step_by_step, binary_search

with open("trace.json") as f:
    trace = json.load(f)

# Choose a method
result = all_at_once(trace, model="gpt-4o")
# result = step_by_step(trace, model="gpt-4o")
# result = binary_search(trace, model="gpt-4o")

print(f"Agent: {result.agent_name}")
print(f"Step:  {result.step_number}")
print(f"Reason: {result.reason}")

Trace Format

A trace is a JSON object with a required history array:

{
  "history": [
    {"role": "assistant", "name": "Excel_Expert", "content": "..."},
    {"role": "user", "name": "Computer_terminal", "content": "..."},
    ...
  ],
  "question": "optional problem description",
  "ground_truth": "optional expected answer"
}

Attribution Methods

Method	Description	LLM Calls
All-at-Once	Feeds entire conversation to the LLM	1
Step-by-Step	Evaluates each step sequentially, stops at first error	Up to N
Binary Search	Recursively narrows down the error location	O(log N)

License

MIT