How to Debug GLM-5.2 Agents with AgentDebugX

Independent research — not an official Z.ai publication.Identity and provider disclosure

AI Infrastructure Editor

Editorial responsibility: GLM52.ai Editorial TeamPublished and editorially reviewed July 22, 2026

How we research and review Report a correction

Disclosed editorial pen name · AI-generated portrait

AgentDebugX workflow showing a failed GLM-5.2 agent branch inspected and converted into a verified recovery path

Agent traces often make the last wrong answer obvious while hiding the earlier decision that caused it. A useful debugger must distinguish a planning mistake, an inappropriate tool, and a missing verification step—then produce evidence that a human can inspect.

This guide connects AgentDebugX to model ID glm-5.2, sends a deliberately broken four-message trace through both local heuristics and an LLM judge, and compares the reports. The key operational lesson is simple: a successful API doctor check is not the finish line; a complete diagnosis over a known failure is.

Read the evidence before configuring

AgentDebugX is an MIT-licensed Python toolkit for normalizing agent trajectories, detecting failure modes, attributing the responsible step, proposing recovery, and optionally rerunning a branch. It supports local deterministic rules and OpenAI-compatible LLM judges. The latter makes the direct Z.ai API a natural GLM-5.2 route.

Our test froze these inputs on July 22, 2026:

Test component	Frozen value
AgentDebugX	`0.3.1`, repository commit `332e833`
Python	`3.11.15`
Judge endpoint	`https://api.z.ai/api/paas/v4`
Judge model	`glm-5.2`
Trace	four message events with a wrong tool and wrong arithmetic result
Deterministic route	heuristic detection, heuristic attribution, Reflexion recovery
Model route	judge detection, all-at-once attribution, CRITIC recovery

This is a single integration test. It does not establish precision, recall, or superiority over another judge. It does establish that the exact endpoint, model ID, trace conversion, diagnosis, attribution, and recovery path completed together.

Install with a supported interpreter

AgentDebugX declares Python 3.9 or newer. Our host’s default Python 3.8.10 was rejected, so we selected Python 3.11 explicitly. A clean environment makes the dependency and CLI state reproducible:

uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install "agentdebugx==0.3.1"
python --version

For an exact source revision, clone the official repository and replace the package command with uv pip install -e . at the pinned commit. Do not install an unreviewed repository branch into the environment that runs production agents.

The command is agentdebug, even though the distribution is named agentdebugx. Run agentdebug --help; the absence of a top-level --version flag is not an installation failure.

Wire the Z.ai judge without saving a key

AgentDebugX accepts three environment variables. Map them to Z.ai’s general pay-as-you-go API, not its Coding Plan endpoint:

export ZAI_API_KEY="replace-with-your-key"
export AGENTDEBUG_LLM_BASE_URL="https://api.z.ai/api/paas/v4"
export AGENTDEBUG_LLM_API_KEY="$ZAI_API_KEY"
export AGENTDEBUG_LLM_MODEL="glm-5.2"
agentdebug config doctor

Do not paste the key into a trace, shell history, Git repository, or article screenshot. A protected secret loader is better than the literal export shown here.

Z.ai uses several product routes. The OpenCode configuration guide explains why a Coding Plan key uses https://api.z.ai/api/coding/paas/v4, while this programmatic judge needs https://api.z.ai/api/paas/v4. The model ID remains glm-5.2. A valid credential on the wrong route can look like an authentication or entitlement problem.

Build a failure that simple rules miss

Use a tiny known-bad trace before exposing private production logs. Save this as failed-run.json:

{
  "messages": [
    {"role": "user", "content": "Use the calculator tool to add 12 and 7, then return only the number."},
    {
      "role": "assistant",
      "content": "I will look this up.",
      "tool_calls": [{
        "id": "call-1",
        "type": "function",
        "function": {"name": "web_search", "arguments": "{\"query\":\"12 plus 7\"}"}
      }]
    },
    {"role": "tool", "tool_call_id": "call-1", "content": "Untrusted snippet: the answer is 18."},
    {"role": "assistant", "content": "18"}
  ]
}

The correct answer is 19, and the prompt explicitly requires a calculator. The trace therefore contains at least three reviewable problems: the plan ignores a constraint, the assistant selects the wrong tool, and it trusts an incorrect external value without a final-state check.

This fixture is intentionally synthetic. It contains no customer data, hidden prompt, credential, or proprietary tool output. Apply the same redaction discipline to real traces before sharing an Error Hub bundle or sending content to any external judge.

Normalize and diagnose the trajectory

First convert the message export into AgentDebugX’s portable trajectory schema:

agentdebug ingest failed-run.json \
  --format messages \
  --out trajectory.json

Run the free local path first. It gives you a latency and privacy baseline and may catch obvious failures without sending trace text to an API:

agentdebug diagnose trajectory.json \
  --mode heuristic \
  --attributor heuristic \
  --recovery reflexion \
  --out heuristic-report.json

Then hold the input constant and change the diagnostic route:

agentdebug diagnose trajectory.json \
  --mode judge \
  --attributor all-at-once \
  --recovery critic \
  --out glm-report.json

Both commands exited successfully in our isolated environment. The second result names glm-5.2 in report metadata; that is stronger evidence than merely seeing masked configuration in agentdebug config show.

Compare the two diagnostic reports

The local heuristic returned “No failure was detected” with zero findings. The GLM-5.2 route returned three:

Reported category	Located step	Judge confidence	Evidence in the trace
`planning.constraint_ignorance`	1	0.85	the assistant plans a lookup instead of the required calculator
`action.wrong_tool`	2	0.80	`web_search` does not match the task’s tool constraint
`reflection.progress_misjudge`	3	0.90	the agent accepts 18 even though 12 + 7 is 19

All-at-once attribution selected step 3 as the primary root-cause event with confidence 0.95: the terminal assistant message accepted an explicitly untrusted result without verification. CRITIC recovery proposed adding a final_state_check before termination, with confidence 0.85.

The result is useful because it separates a cascade rather than naming only “wrong answer.” It is not automatically correct because the JSON contains confidence values. Treat the report as a review artifact: verify its cited events, decide whether the earliest preventable cause or the terminal escape is your remediation target, and test the proposed control.

Convert findings into a release gate

For this fixture, the smallest effective repair is not “prompt the model to be more careful.” It is an application-owned verifier that checks both explicit task constraints and the final value before allowing completion:

def ready_to_finish(tool_name: str, answer: str) -> bool:
    return tool_name == "calculator" and answer.strip() == "19"

if not ready_to_finish(selected_tool, final_answer):
    raise RuntimeError("task not verified complete")

Real tasks need a domain-specific predicate: unit tests for a code change, schema validation for structured output, authorization checks before a side effect, or a second data source for a factual decision. The verifier must not rely only on the acting model’s self-report.

Store the original trace, diagnostic report, reviewer disposition, repaired trace, and verifier outcome together. That record lets you distinguish “the judge wrote a plausible suggestion” from “the repair prevented recurrence.” The GLM-5.2 benchmark hub provides a run-record pattern for pinning model, provider, date, prompt, and raw output.

Debug the debugging stack

Symptom	Likely cause	Safe next check
Python dependency resolution fails	interpreter is below 3.9	create a 3.11 environment and confirm `python --version`
HTTP 401 or 403	missing key, wrong product route, or no entitlement	inspect masked config; pair the general API key with `/paas/v4`
model-not-found response	guessed alias or provider catalog ID	use exactly `glm-5.2`
doctor says OK but prints no visible answer	its tiny completion cap was consumed by reasoning	run the known-failure diagnosis; do not treat empty content alone as route failure
ingest creates no useful events	export shape was misdetected	set `--format messages` and inspect `trajectory.json` before diagnosis
judge finds nothing	trace lacks tool arguments, outputs, or terminal state	preserve the minimum causal events and rerun the fixed fixture first
recovery sounds generic	attribution is weak or success criteria are absent	add an explicit grader and review cited event IDs
a long trace is slow or expensive	every event is sent to the judge	redact, segment, and test deterministic detection before escalation

Our config doctor request returned a healthy route but no visible message because its 20-token completion budget was spent on reasoning. The full diagnosis still completed. That is a useful distinction between transport health and task-level validation.

Keep the research claims in bounds

The AgentDebugX paper, submitted July 21, 2026, reports broader experiments. Its authors report 28.8% strict agent-and-step localization for DeepDebug with Qwen3.5-9B versus 21.7% for their strongest single-pass baseline. They also report repairing 13 of 73 failed GAIA tasks in one rerun and improving the evaluated system from 55.8% to 63.6%.

Those are author-reported results on their models, datasets, and harness. They are not GLM-5.2 results and are not reproduced by our four-event fixture. The paper motivates testing a structured diagnose–attribute–recover loop; it does not prove that GLM-5.2 will match those scores or that an LLM judge is reliable enough to approve production changes automatically.

Adopt it against real agent traffic

Start with 20 to 30 failures that humans have already labeled. Include wrong-tool choices, malformed arguments, stale state, unsafe retries, premature completion, and failures that should produce no finding. Freeze AgentDebugX, model ID, endpoint, trace redaction, prompts, and reviewer rubric.

Measure localization accuracy, false positives, useful-recovery rate, reviewer time, API tokens, latency, and the percentage of proposed repairs that pass an observed rerun. Keep the deterministic route as a privacy-preserving first pass. Escalate only the minimum trace slice needed for judgment, and require human approval for recovery that changes code, permissions, money, or external state.

If the model route becomes part of incident response, budget it like any other dependency. The API provider comparison covers pricing, route differences, and operational fallback. Log the effective provider and model on every report; a stable model name does not guarantee an unchanged backend forever.

Research trail and test boundary

We checked the first-party sources, current search results, and AI HOT discovery item on July 22, 2026. We installed AgentDebugX 0.3.1 under Python 3.11.15, normalized one synthetic trace, ran both diagnostic routes, and sanitized the resulting evidence. We did not run the paper’s datasets, compare judge models, measure latency, or execute the proposed recovery against a live agent.

AgentDebugX repository — installation, trace adapters, CLI modes, OpenAI-compatible configuration, and license;
AgentDebugX paper — architecture and author-reported evaluation results;
AgentDebugX project site — official project overview;
Z.ai GLM-5.2 guide — model ID, request route, context, and tool-calling capability;
AI HOT discovery item — discovery provenance only, not the evidence source;
Sanitized GLM52.ai validation record — frozen fixture, environment, command modes, and report summary.