Agent WorkflowsA field guide by Doruk

Diagnose a run with the CLI

This guide works through the same CI run as the UI manual: ████████, CI run ███████████ of the ██████████-ai/██████████-Frontend-V2 trial workflow, recorded on 2026-10-05. Use it when you need exact totals, a comparison between runs, or an agent to do the diagnosis. Every command and output below is from that session. Long paths are shortened to ….

Run every command under the /telemetry credentials, as described in Observability:

█████████ run --domain "$█████████_URL" --projectId "$█████████_PROJECT_ID" \
  --env lab --path /telemetry --include-imports=false --recursive=false --expand=false -- \
  <command>

npx langfuse-cli api __schema lists the resources. npx langfuse-cli api observations list --help lists the filters and the --fields groups.

1. Check that the agent step is the slow part

gh run view ███████████ --repo ██████████-ai/██████████-Frontend-V2 --json jobs \
  --jq '.jobs[0].steps[] | select(.conclusion == "success" and (.name | startswith("Post") | not)) | "\(.name)\t\(((.completedAt|fromdate)-(.startedAt|fromdate)))s"'
Set up job	56s
Show run configuration	0s
Fetch Jira packet and prepare verification	66s
Check verification readiness	17s
Initialize verification	38s
Verify ACs and capture evidence	459s
Validate report and collect traces	3s
Publish report to Drive	55s
Report outcome and upload evidence	7s
Complete job	1s

The agent step takes 459 s of 702 s, which is 65% of the job, so the trace can answer the question.

2. Find the run’s trace

npx langfuse-cli api observations list --name claude_code.interaction \
  --from-start-time 2026-10-05T00:00:00Z --fields core,metadata,metrics --limit 100 \
  | jq -r --arg t ████████ '.data[] | select(.metadata["resourceAttributes.ac.ticket"] == $t)
      | "\(.startTime) trace=\(.traceId) agent=\(.latency)s run=\(.metadata["resourceAttributes.cicd.pipeline.run.id"] // "local")"'
2026-10-05T08:46:52.174Z trace=████████████████████████████████ agent=446.041s run=███████████
2026-10-05T08:32:20.374Z trace=████████████████████████████████ agent=505.857s run=local

The run value matches the GitHub run. The local run of the same ticket is used in step 7.

3. Split model time from tool time

npx langfuse-cli api observations list --trace-id ████████████████████████████████ \
  --fields core,basic,metrics --limit 1000 \
  | jq -r '.data | map(select(.name == "claude_code.interaction" or .name == "claude_code.llm_request" or .name == "claude_code.tool"))
      | group_by(.name)[] | "\(.[0].name)\t\(length)\t\((map(.latency // 0) | add) | floor)s"'
claude_code.interaction  1   446s
claude_code.llm_request  41  403s
claude_code.tool         54  32s

This is the decision point. The model takes 403 of 446 s, which is 90%. Tools take 32 s. The run is model-bound, and faster tools would save at most 32 s. If tools held most of the time, the run would be tool-bound, as with ████████’s 449 s polling loop, and step 4 would name the command to fix.

4. List the slowest tool calls

npx langfuse-cli api observations list --trace-id ████████████████████████████████ --name claude_code.tool \
  --fields core,metadata,metrics --expand-metadata attributes.full_command --limit 1000 \
  | jq -r '.data | map(select(.latency != null)) | sort_by(-.latency) | .[0:5][]
      | "\(.latency)s  \(.metadata["attributes.full_command"] // .metadata["attributes.tool_name"])"'
7.814s  node session.mjs screenshot --sequence 9 --slug plans-page-popover-closed --full-page false --selection …
echo
node session.mjs trace-stop --sequence 10 --selection … 2>&1 | head -c 500
echo
node session.mjs video-stop --sequence 11 --selection … 2>&1 | head -c 1500
6.642s  node session.mjs open --selection … 2>&1
6.095s  node session.mjs video-start --sequence 5 --ac AC1 --slug profile-popover-view-plans --selection … 2>&1
1.619s  echo "=== packet dir ==="; ls -la … echo "=== source-evidence dir ==="; ls -la …
1.598s  node session.mjs click --sequence 8 --ref f3e572 --selection … 2>&1

One tool call can hold several commands. The 7.8 s call is a screenshot, trace-stop and video-stop together. Browser capture takes a few seconds per call, so it is not the problem.

5. Find what the long model requests led to

A request’s latency is mostly the time spent writing output. Pair each long request with the next tool call to see what that output was for:

npx langfuse-cli api observations list --trace-id ████████████████████████████████ \
  --fields core,basic,metadata,metrics --expand-metadata attributes.full_command,attributes.file_path --limit 1000 \
  | jq -r '(.data | map(select(.latency != null)) | sort_by(.startTime)) as $o
      | ($o | map(select(.name == "claude_code.tool"))) as $t
      | $o[] | select(.name == "claude_code.llm_request" and .latency > 20) as $g
      | ([ $t[] | select(.startTime >= $g.endTime) ][0]) as $n
      | "\($g.startTime[11:19]) model \($g.latency)s out=\($g.metadata["attributes.output_tokens"]) → next: \($n.metadata["attributes.tool_name"] // "end") \($n.metadata["attributes.file_path"] // $n.metadata["attributes.full_command"] // "")"'
08:49:28 model 25.72s out=2378 → next: Bash cd …/ac-walkthrough-plugin && grep -rn "unverified" runtime/scripts/ | grep -v node_module…
08:49:59 model 100.682s out=9722 → next: Bash find runtime/scripts/fixtures -iname "*.md" | xargs grep -l "technical-evidence" …
08:52:19 model 42.808s out=4685 → next: Edit …/████████-ac-verification-v5.walkthrough.md
08:53:27 model 22.241s out=3198 → next: Edit …/████████-ac-verification-v5.walkthrough.md

The 100.7 s request drafts the report: 9,722 output tokens. Then, before the first edit, the agent searches the runtime and fixtures for format examples.

6. Find failed commands

npx langfuse-cli api observations list --trace-id ████████████████████████████████ \
  --fields core,basic,metadata --expand-metadata attributes.full_command --limit 1000 \
  | jq -r '.data as $all | $all[] | select(.level == "ERROR") as $e
      | ($all[] | select(.id == $e.parentObservationId)) as $p
      | "\($e.startTime[11:19]) \($e.statusMessage)  \($p.metadata["attributes.full_command"])"'
08:53:07 Shell command failed  cd … && node "████████████████████████████████████.mjs" render "…" "████████" "…" 2>&1
08:51:40 Shell command failed  find runtime/scripts/fixtures -iname "*.md" | xargs grep -l "technical-evidence"

Both failures fit the same story:

  • the format search right after the draft found nothing;
  • the first render rejected the report, which led to the 08:53:27 request, an edit, and a successful re-render at 08:53:54.

--level ERROR on its own lists the failed executions without their commands.

7. Compare with another run

Repeat step 3 for the local run, trace ████████████████████████████████:

CI run ███████████ Local run (v7)
Agent wall time 446 s 506 s
Model requests 41, 403 s 51, 7.8 min
Tool calls 54, 32 s 60, 29.5 s
Longest model request 100.7 s, 9,722 tokens 1.7 min, 10,745 tokens

Both runs have the same shape. One run can mislead, but two runs that agree make the finding actionable.

8. Decide

Evidence Next step
Model-bound, with format searches and a rejected render during authoring (steps 3, 5, 6, 7) Give the agent the report format before it starts writing. Success looks like fewer generations after the draft, no failed render, and a shorter claude_code.interaction.
One tool call over a minute (████████) Fix that command, or give the agent a bounded wait instead of improvised polling.
Neither Turn count sets the time. Reduce turns, not tool time.

After a change, rerun the ticket and repeat steps 2–3. The two traces are the before-and-after evidence.

Files