Observability ng AI agent: paano malalaman kung ano ang ginawa ng agent at ano ang dapat i-log

Ano ang observability ng AI agent

Ang observability ng AI agent ay ang kakayahang sagutin, batay sa mga artifact at hindi sa alaala o sa sinasabi ng agent, ang tatlong tanong: ano ang ginawa niya, bakit ganoon ang ginawa niya at ano ang nagpapatunay nito, at tama ba ang resulta. Kung pagkatapos ng dalawampung minutong trabaho ay sinabi ng agent na "tapos na, pero dalawang test ang pumapalya, baka dahil sa timing," at kapag tinanong kung aling mga path ang naapektuhan ay "patingnan muna ninyo ang code," walang observability. Hindi tanga ang agent; wala lang siyang maipakita.

Sistematiko ang problema. Maaaring sampung beses sa isang linggo na taos-pusong sabihin ng parehong agent na "tapos na," at bawat isa ay may ibang kahulugan: may lugar kung saan lahat ng test ang pinatakbo, may lugar na isa lang, at may lugar na wala talaga. Habang tumatagal ang proyekto, lalong nagiging mahal ang bawat susunod na session, dahil nagsisimula ito sa paghukay.

Dalawang patong: runtime at proseso

Madalas malito ang observability sa logs, pero kalahati lang ang logs.

Runtime lamang: nakikita ang pumalya, pero hindi malinaw kung ano ang hinahangad. Proseso lamang: malinaw ang hinahangad, pero hindi nakikita kung bakit hindi ito nagtagumpay. Kailangan ang dalawa.

Bakit hindi ito magagawa ng agent nang mag-isa

Hindi gagana ang sabihing "mag-log kayo nang mas mabuti" sa agent, sa tatlong dahilan.

• Hindi niya alam ang hindi niya alam. Hindi niya ilo-log ang senyales na hindi niya nahuhulaang mahalaga.
• Nagbabago ang format. Sa isang session ay detalyado siya, sa iba ay isang linya lang. Hindi maihahambing ang mga session at hindi mabibilang ang kabuuan.
• Hindi kayang isara ng logs ang proseso. Ang sagot sa tanong na "bakit ganito" ay nasa mga dokumentong ginawa bago ang trabaho, hindi sa output ng mga command.

Kaya ang observability ay itinatanim sa harness — ang environment ng agent: mga template, hooks, script, at sapilitang format ng ulat.

Ano ang dapat i-log: pinakakaunting kailangan

Ang mabuting journal ay hindi buong transcript ng lahat, kundi koleksyon ng mga katotohanang makakapagbuo muli ng takbo ng trabaho at makakapagbilang ng estadistika.

• Mga identifier: ID ng session, ID ng gawain o feature, modelo ng agent.
• Mga aksyong may side effect: aling mga command ang pinatakbo, aling mga file ang binago. Karaniwang hindi na kailangang itala ang pagbasa ng file.
• Resulta ng mga pagsusuri: aling command ng pagsusuri, return code, ilang test ang pumasa at pumalya.
• Mga retry: ilang pagsubok ang ginawa sa isang hakbang at ano ang pagkakaiba nila.
• Gastos: token at oras, kung ibinibigay ito ng tool.
• Kinalabasan: tinanggap, tinanggihan, o iniwan ang gawain, at bakit.

Ang hindi dapat isulat: mga secret, access token, at personal na datos mula sa output ng mga command. Maaaring mapunta ang journal sa pampublikong access o muli sa context ng modelo.

Journal ng aksyon gamit ang hooks ng Claude Code

Sa Claude Code, maginhawang panatilihin ang journal gamit ang hooks — mga command na pinapatakbo mismo ng tool, hindi ng modelo, kaya laging tumatakbo ang mga ito. Tumatanggap ang hook ng JSON na naglalarawan ng event bilang input, kasama ang ID ng session, pangalan ng tool, at mga parameter nito. Ito ang halimbawa ng setup sa .claude/settings.json na pagkatapos ng bawat tawag ng Bash, Edit, o Write ay nagdaragdag ng linya sa journal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — isang JSON na linya bawat aksyon
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Maginhawa ang format na JSONL (isang JSON record bawat linya) dahil madaling i-filter gamit ang jq at i-load sa anumang sistema ng pagsusuri. Bukod dito, iniimbak din ng Claude Code nang lokal ang buong kasaysayan ng session sa direktoryong ~/.claude/projects/ — mabubuksan ito kung gusto ninyong makita nang buo ang pangangatwiran at output, pero para sa estadistika, mas maginhawa ang sarili ninyong compact na journal.

Tracing: isang trace bawat session, isang span bawat gawain

Kapag marami ang agent o tumatakbo ayon sa iskedyul, kulang ang mga text log: kailangan ang mga agregado. Dito kapaki-pakinabang ang karaniwang mga tool ng distributed tracing at ang pamantayang OpenTelemetry.

• Trace — isang session ng agent.
• Span — isang gawain sa loob ng session.
• Mga nested span — mga hakbang ng beripikasyon: build, test, e2e.

Pinakakaunting attribute bawat span: ID ng feature at session, modelo, resulta ng pagsusuri, token, at bilang ng retry. Nababasa ang ganitong datos sa Jaeger, Grafana Tempo, at Honeycomb, at nasasagot nito ang mga tanong na hindi makikita sa iisang session: aling uri ng gawain ang madalas nangangailangan ng retry, saan gumagastos ng pinakamaraming token ang agent, at pagkatapos ng aling pagbabago sa harness bumaba ang bahagi ng tinanggap na gawain. May built-in na pagpapadala ng metrics at event ang Claude Code sa pamamagitan ng OpenTelemetry — naka-enable ito gamit ang environment variables; ang detalye ay nasa dokumentasyon ng tool.

Commits bilang journal

Ang pinakamurang at pinakamaaasahang journal ay nasa inyo na — ang git. Kailangan lang itong gawing mabasa.

1. Isang commit — isang gawain. Sa ganitong paraan, tumutugma ang git log sa listahan ng nagawa, at ang rollback ng gawain ay iisang git revert.
2. Sa mensahe — ano ang binago at paano ito nasuri. Hindi "fix" lang, kundi ano ang binago, bakit, at anong command ang nagpatunay nito.
3. Mag-commit lamang pagkatapos ng berdeng pagsusuri. Sa ganitong paraan, bawat punto sa kasaysayan ay gumaganang estado, at nahahanap ng git bisect ang may sala.

fix(payments): round-off ng diskwento hanggang sentimo

Ang diskwento ay kinakalkula sa float, sa halagang 999.99 nawawala ang isang sentimo.
Inilipat ang kalkulasyon sa int sa sentimo.
Nasuri: make test (142 passed), make e2e checkout — ok.
Labas sa saklaw: round-off sa mga ulat, nakatala sa BACKLOG.md.

Ulat ng agent: patunay sa halip na impresyon

Ang huling mensahe ng agent ay artifact din ng observability, kung may nakapirming anyo. Isulat ang template sa AGENTS.md o CLAUDE.md:

## Ulat sa dulo ng gawain
- Ano ang ginawa: listahan ng mga pagbabago (file — esensya)
- Paano nasuri: eksaktong mga command at ang resulta nito
- Ano ang HINDI nasuri at bakit
- Mga paglihis sa kasunduan ng gawain
- Mga bukas na tanong para sa tao

Ang pangunahing panuntunan: bawat pahayag ay may kasamang patunay — file at linya, output ng test, o tala sa journal. Hindi ituturing na ulat ang "mukhang maayos" at "sa tingin ko ok." Mahalaga lalo ang punto na "ano ang hindi nasuri" dahil tapat nitong ipinapakita ang hangganan ng katiyakan.

Kasunduan bago ang code at rubric pagkatapos

Nagsisimula ang patong ng proseso bago ang trabaho. Itinatala ng maikling kasunduan sa gawain (sprint contract) ang saklaw, pamantayan sa pagtanggap, seksyong "labas sa saklaw," at mga bukas na tanong na tao ang magpapasya. Pinipigilan ng seksyong "labas sa saklaw" ang kalahati ng pagtatalo tungkol sa resulta.

Pagkatapos ng trabaho, sinusuri ang resulta ayon sa rubric, hindi ayon sa impresyon. Kung hindi, magbibigay ng magkaibang hatol ang dalawang bihasang reviewer, at magiging sugal ang pagsusuri.

Bawat sukat ay tinatasahan ng A/B/C/D, at walang bisa ang tasa na walang link. Simpleng panuntunan sa desisyon: isang D o dalawang C — tanggihan na may listahan ng dapat ayusin. Maaari ring gamitin ang parehong rubric ng hiwalay na agent na tagasuri.

Paano suriin kung ano ang ginawa ng agent sa isang session

Kung walang ulat o hindi ito mapagkakatiwalaan, dumaan sa mga artifact sa sumusunod na pagkakasunod-sunod.

1. Estado ng tree: git status — ano ang hindi pa naka-commit, at may basurang file ba.
2. Kasaysayan: git log --stat mula sa simula ng session — aling mga commit at file.
3. Saklaw ng mga pagbabago: git diff --stat main...HEAD, saka ang buong diff ng mahahalagang file.
4. Journal ng aksyon: aling mga command ang pinatakbo at ano ang ibinalik ng mga pagsusuri.
5. Muling pagsusuri: kayo mismo ang magpatakbo ng build at test. Pagkatiwalaan ang output ng command, hindi ang pagsasalaysay.

# aling mga command ang pinatakbo ng agent sa huling session
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# aling mga file ang madalas binago
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Karaniwang pagkakamali

• Pag-log ng lahat. Walang nagbabasa ng mga gigabyte ng transcript. Isulat ang mga aksyong may side effect at ang mga resulta ng pagsusuri.
• Malayang format. Kung ang agent ang nagtatakda ng format ng journal, walang agregado. Ang harness ang dapat magtakda ng format.
• Pagtitiwala sa ulat nang walang output ng command. Ang "berde ang test" nang walang output ay opinyon lamang.
• Bulag na retry. Kung walang dahilan ng pagkabigo, binabago ng agent ang mga random na bahagi. Hingin muna ang diagnosis na may link sa log, saka ang pag-aayos.
• "Lilinisin na lang mamaya." Ang mga debug file at hindi naka-commit na pagbabago ay nakalilito sa susunod na session: hindi nito malalaman kung alin ang pansamantala at alin ang sinadya.

Buod

Binubuo ang observability ng AI agent ng dalawang patong: runtime (journal ng aksyon sa pamamagitan ng hooks, traces, commit na may paglalarawan ng pagsusuri) at proseso (kasunduan sa gawain bago ang code, rubric, at ulat na may link sa ebidensya). Sa ganitong paraan, pareho ang ibig sabihin ng "tapos na" sa bawat session, at ilang minuto na lang ang pagsusuri sa ginawa ng agent. Tinatalakay ito nang praktikal sa kursong harness engineering, sa isang buong proyekto ng payment backend.