[{"data":1,"prerenderedAt":633},["ShallowReactive",2],{"docs-\u002Fdocs\u002Fv2\u002Ffleet\u002Fdebugging":3},{"id":4,"title":5,"body":6,"description":16,"extension":627,"meta":628,"navigation":98,"path":629,"seo":630,"stem":631,"__hash__":632},"docs\u002Fdocs\u002Fv2\u002Ffleet\u002Fdebugging\u002Findex.md","Debugging in Code",{"type":7,"value":8,"toc":618},"minimark",[9,13,17,26,31,39,42,134,137,141,147,229,235,359,362,366,369,393,397,400,510,513,517,520,554,557,561,564,575,585,591,595,598,604,607,614],[10,11,5],"h1",{"id":12},"debugging-in-code",[14,15,16],"p",{},"Debugging one agent is reading its trace. Debugging several is the same skill applied\nN times, plus one new problem: working out which trace to read.",[14,18,19,20,25],{},"This page is what you can do from inside the script. The pages after it are the\n",[21,22,24],"a",{"href":23},"\u002Fdocs\u002Fv2\u002Ffleet\u002Fdebugging\u002Fconsole","Console"," — the same traces, read properly.",[27,28,30],"h2",{"id":29},"every-agent-traces-itself","Every agent traces itself",[14,32,33,34,38],{},"Each agent writes its own session to its own ",[35,36,37],"code",{},"data\u002Fsessions\u002F"," as a JSONL trace — every\nrequest, every tool call, every result, every error. Three agents in a script produce\nthree traces in three folders.",[14,40,41],{},"That is a consequence of the boundary, not an oversight. Agents don't share memory, so\nthey don't share a log. Each trace is complete and readable on its own, which means you\ncan debug one agent's behaviour without untangling it from the others.",[43,44,49],"pre",{"className":45,"code":46,"language":47,"meta":48,"style":48},"language-ts shiki shiki-themes dark-plus","const { barry } = await Fleet({ barry: \"..\u002Fbarry\" })\n\nconsole.log(barry.session.id)   \u002F\u002F which trace to read\n","ts","",[35,50,51,93,100],{"__ignoreMap":48},[52,53,56,60,64,68,71,75,79,82,86,90],"span",{"class":54,"line":55},"line",1,[52,57,59],{"class":58},"scz_3","const",[52,61,63],{"class":62},"sTNBD"," { ",[52,65,67],{"class":66},"s9McN","barry",[52,69,70],{"class":62}," } = ",[52,72,74],{"class":73},"sYbnZ","await",[52,76,78],{"class":77},"sCudf"," Fleet",[52,80,81],{"class":62},"({ ",[52,83,85],{"class":84},"s3F5K","barry:",[52,87,89],{"class":88},"sKc5r"," \"..\u002Fbarry\"",[52,91,92],{"class":62}," })\n",[52,94,96],{"class":54,"line":95},2,[52,97,99],{"emptyLinePlaceholder":98},true,"\n",[52,101,103,106,109,112,115,117,119,122,124,127,130],{"class":54,"line":102},3,[52,104,105],{"class":84},"console",[52,107,108],{"class":62},".",[52,110,111],{"class":77},"log",[52,113,114],{"class":62},"(",[52,116,67],{"class":84},[52,118,108],{"class":62},[52,120,121],{"class":84},"session",[52,123,108],{"class":62},[52,125,126],{"class":84},"id",[52,128,129],{"class":62},")   ",[52,131,133],{"class":132},"sOLPB","\u002F\u002F which trace to read\n",[14,135,136],{},"Print the session IDs at the top of any multi-agent script. It costs one line and it is\nthe difference between finding the right file in seconds and grepping by timestamp.",[27,138,140],{"id":139},"watching-live","Watching live",[14,142,143,146],{},[35,144,145],{},"session.entries"," is the live log — readable while the agent is working:",[43,148,150],{"className":45,"code":149,"language":47,"meta":48,"style":48},"const before = barry.session.entries.length\nawait barry.request(\"audit the repo\")\nconst produced = barry.session.entries.slice(before)\n",[35,151,152,178,198],{"__ignoreMap":48},[52,153,154,156,159,162,164,166,168,170,173,175],{"class":54,"line":55},[52,155,59],{"class":58},[52,157,158],{"class":66}," before",[52,160,161],{"class":62}," = ",[52,163,67],{"class":84},[52,165,108],{"class":62},[52,167,121],{"class":84},[52,169,108],{"class":62},[52,171,172],{"class":84},"entries",[52,174,108],{"class":62},[52,176,177],{"class":84},"length\n",[52,179,180,182,185,187,190,192,195],{"class":54,"line":95},[52,181,74],{"class":73},[52,183,184],{"class":84}," barry",[52,186,108],{"class":62},[52,188,189],{"class":77},"request",[52,191,114],{"class":62},[52,193,194],{"class":88},"\"audit the repo\"",[52,196,197],{"class":62},")\n",[52,199,200,202,205,207,209,211,213,215,217,219,222,224,227],{"class":54,"line":102},[52,201,59],{"class":58},[52,203,204],{"class":66}," produced",[52,206,161],{"class":62},[52,208,67],{"class":84},[52,210,108],{"class":62},[52,212,121],{"class":84},[52,214,108],{"class":62},[52,216,172],{"class":84},[52,218,108],{"class":62},[52,220,221],{"class":77},"slice",[52,223,114],{"class":62},[52,225,226],{"class":84},"before",[52,228,197],{"class":62},[14,230,231,234],{},[35,232,233],{},"on()"," subscribes to what the agent emits as it emits it, which is how you build a live\nview over several agents at once:",[43,236,238],{"className":45,"code":237,"language":47,"meta":48,"style":48},"for (const [name, agent] of Object.entries({ barry, checker })) {\n    agent.on(\"text\", ({ content }) => process.stdout.write(`[${name}] ${content}`))\n}\n",[35,239,240,287,354],{"__ignoreMap":48},[52,241,242,245,248,250,253,256,259,262,265,268,271,273,275,277,279,281,284],{"class":54,"line":55},[52,243,244],{"class":73},"for",[52,246,247],{"class":62}," (",[52,249,59],{"class":58},[52,251,252],{"class":62}," [",[52,254,255],{"class":66},"name",[52,257,258],{"class":62},", ",[52,260,261],{"class":66},"agent",[52,263,264],{"class":62},"] ",[52,266,267],{"class":58},"of",[52,269,270],{"class":84}," Object",[52,272,108],{"class":62},[52,274,172],{"class":77},[52,276,81],{"class":62},[52,278,67],{"class":84},[52,280,258],{"class":62},[52,282,283],{"class":84},"checker",[52,285,286],{"class":62}," })) {\n",[52,288,289,292,294,297,299,302,305,308,311,314,317,319,322,324,327,329,332,335,337,340,342,344,346,348,351],{"class":54,"line":95},[52,290,291],{"class":84},"    agent",[52,293,108],{"class":62},[52,295,296],{"class":77},"on",[52,298,114],{"class":62},[52,300,301],{"class":88},"\"text\"",[52,303,304],{"class":62},", ({ ",[52,306,307],{"class":84},"content",[52,309,310],{"class":62}," }) ",[52,312,313],{"class":58},"=>",[52,315,316],{"class":84}," process",[52,318,108],{"class":62},[52,320,321],{"class":84},"stdout",[52,323,108],{"class":62},[52,325,326],{"class":77},"write",[52,328,114],{"class":62},[52,330,331],{"class":88},"`[",[52,333,334],{"class":58},"${",[52,336,255],{"class":84},[52,338,339],{"class":58},"}",[52,341,264],{"class":88},[52,343,334],{"class":58},[52,345,307],{"class":84},[52,347,339],{"class":58},[52,349,350],{"class":88},"`",[52,352,353],{"class":62},"))\n",[52,355,356],{"class":54,"line":102},[52,357,358],{"class":62},"}\n",[14,360,361],{},"Prefixing by name is the cheap version of the correlated view — enough to follow two\nagents interleaving in a terminal.",[27,363,365],{"id":364},"reading-the-trace","Reading the trace",[14,367,368],{},"The trace records what the model actually saw and did, tick by tick — the assembled\ncontext, the output, the code that ran, the results. When an agent does something\nunexpected, this is where the answer is, and it is usually in the context rather than\nthe response: the agent did the right thing with the wrong information.",[14,370,371,372,376,377,380,381,384,385,388,389,392],{},"Entry types are documented under ",[21,373,375],{"href":374},"\u002Fdocs\u002Fv2\u002Fapi\u002Fthread\u002Findex","Entries",". The ones you\nreach for most: ",[35,378,379],{},"axon:agent:message"," for what it said, ",[35,382,383],{},"capsule:stdin"," and\n",[35,386,387],{},"capsule:stdout"," for what it ran, ",[35,390,391],{},"capsule:denied"," for what policy stopped.",[27,394,396],{"id":395},"which-agent-is-wrong","Which agent is wrong?",[14,398,399],{},"With several agents, the first question is where the failure entered. A pipeline makes\nthis tractable, because each stage's input is a value in your script:",[43,401,403],{"className":45,"code":402,"language":47,"meta":48,"style":48},"const findings = await scout.request(\"find every caller\")\nconsole.log(\"--- findings ---\\n\", findings.text)   \u002F\u002F check before passing on\n\nconst plan = await planner.request(`plan a refactor.\\n\\n${findings.text}`)\n",[35,404,405,430,465,469],{"__ignoreMap":48},[52,406,407,409,412,414,416,419,421,423,425,428],{"class":54,"line":55},[52,408,59],{"class":58},[52,410,411],{"class":66}," findings",[52,413,161],{"class":62},[52,415,74],{"class":73},[52,417,418],{"class":84}," scout",[52,420,108],{"class":62},[52,422,189],{"class":77},[52,424,114],{"class":62},[52,426,427],{"class":88},"\"find every caller\"",[52,429,197],{"class":62},[52,431,432,434,436,438,440,443,447,450,452,455,457,460,462],{"class":54,"line":95},[52,433,105],{"class":84},[52,435,108],{"class":62},[52,437,111],{"class":77},[52,439,114],{"class":62},[52,441,442],{"class":88},"\"--- findings ---",[52,444,446],{"class":445},"svVle","\\n",[52,448,449],{"class":88},"\"",[52,451,258],{"class":62},[52,453,454],{"class":84},"findings",[52,456,108],{"class":62},[52,458,459],{"class":84},"text",[52,461,129],{"class":62},[52,463,464],{"class":132},"\u002F\u002F check before passing on\n",[52,466,467],{"class":54,"line":102},[52,468,99],{"emptyLinePlaceholder":98},[52,470,472,474,477,479,481,484,486,488,490,493,496,498,500,502,504,506,508],{"class":54,"line":471},4,[52,473,59],{"class":58},[52,475,476],{"class":66}," plan",[52,478,161],{"class":62},[52,480,74],{"class":73},[52,482,483],{"class":84}," planner",[52,485,108],{"class":62},[52,487,189],{"class":77},[52,489,114],{"class":62},[52,491,492],{"class":88},"`plan a refactor.",[52,494,495],{"class":445},"\\n\\n",[52,497,334],{"class":58},[52,499,454],{"class":84},[52,501,108],{"class":62},[52,503,459],{"class":84},[52,505,339],{"class":58},[52,507,350],{"class":88},[52,509,197],{"class":62},[14,511,512],{},"Most multi-agent bugs are not agent bugs. They are prompt bugs at a handoff — one agent\nproduced something reasonable, and the next agent received it without the context needed\nto interpret it. Printing what crosses each boundary finds this faster than reading\neither trace.",[27,514,516],{"id":515},"isolating-one-agent","Isolating one agent",[14,518,519],{},"Because agents are independent, you can run one on its own with the same input and see\nwhether it misbehaves outside the composition:",[43,521,525],{"className":522,"code":523,"language":524,"meta":48,"style":48},"language-bash shiki shiki-themes dark-plus","axon                              # boot it in the TUI, talk to it directly\naxon run review --file src\u002Fx.ts   # run its own script headlessly\n","bash",[35,526,527,535],{"__ignoreMap":48},[52,528,529,532],{"class":54,"line":55},[52,530,531],{"class":77},"axon",[52,533,534],{"class":132},"                              # boot it in the TUI, talk to it directly\n",[52,536,537,539,542,545,548,551],{"class":54,"line":95},[52,538,531],{"class":77},[52,540,541],{"class":88}," run",[52,543,544],{"class":88}," review",[52,546,547],{"class":58}," --file",[52,549,550],{"class":88}," src\u002Fx.ts",[52,552,553],{"class":132},"   # run its own script headlessly\n",[14,555,556],{},"If it behaves alone and misbehaves in the fleet, the problem is what you handed it. If\nit misbehaves alone, it is an agent problem — debug it as one agent.",[27,558,560],{"id":559},"determinism","Determinism",[14,562,563],{},"Multi-agent runs vary between executions, which makes a bug that appeared once hard to\nreproduce. Pin what you can:",[14,565,566,570,571,108],{},[567,568,569],"strong",{},"Use the mock engine"," for the parts under test. It makes agent responses deterministic,\nso a failing composition fails the same way twice. See\n",[21,572,574],{"href":573},"\u002Fdocs\u002Fv2\u002Fagent\u002Ftesting","Testing",[14,576,577,580,581,584],{},[567,578,579],{},"Pin registry versions."," An unpinned fleet member can change under you between runs;\n",[35,582,583],{},"@arclabs\u002Flinter@1.2.0"," cannot.",[14,586,587,590],{},[567,588,589],{},"Keep handoffs in variables."," Text passed between agents through a named variable is\ninspectable, loggable, and replayable. Inline template strings are none of those.",[27,592,594],{"id":593},"known-gap-no-unified-run-view","Known gap: no unified run view",[14,596,597],{},"There is no single artifact representing \"this run across all its agents.\" Traces are\nper-agent, and joining them is still done by hand.",[14,599,600,601,603],{},"Each one is complete on its own, and the ",[21,602,24],{"href":23},"\nreads any of them — live or finished — so the missing piece is correlation across\nseveral, not depth within one. Until it exists, printing session IDs and prefixing live\noutput is the practical substitute.",[605,606],"hr",{},[14,608,609,610,613],{},"Next: ",[21,611,612],{"href":23},"The Console"," — reading a trace without reading\nJSONL.",[615,616,617],"style",{},"html pre.shiki code .scz_3, html code.shiki .scz_3{--shiki-default:#569CD6}html pre.shiki code .sTNBD, html code.shiki .sTNBD{--shiki-default:#D4D4D4}html pre.shiki code .s9McN, html code.shiki .s9McN{--shiki-default:#4FC1FF}html pre.shiki code .sYbnZ, html code.shiki .sYbnZ{--shiki-default:#C586C0}html pre.shiki code .sCudf, html code.shiki .sCudf{--shiki-default:#DCDCAA}html pre.shiki code .s3F5K, html code.shiki .s3F5K{--shiki-default:#9CDCFE}html pre.shiki code .sKc5r, html code.shiki .sKc5r{--shiki-default:#CE9178}html pre.shiki code .sOLPB, html code.shiki .sOLPB{--shiki-default:#6A9955}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .svVle, html code.shiki .svVle{--shiki-default:#D7BA7D}",{"title":48,"searchDepth":95,"depth":95,"links":619},[620,621,622,623,624,625,626],{"id":29,"depth":95,"text":30},{"id":139,"depth":95,"text":140},{"id":364,"depth":95,"text":365},{"id":395,"depth":95,"text":396},{"id":515,"depth":95,"text":516},{"id":559,"depth":95,"text":560},{"id":593,"depth":95,"text":594},"md",{},"\u002Fdocs\u002Fv2\u002Ffleet\u002Fdebugging",{"title":5,"description":16},"docs\u002Fv2\u002Ffleet\u002Fdebugging\u002Findex","OaE9N4x2zS6aifVXaWR7jIlc97y83At1JZacRojDCwk",1786104361072]