[{"data":1,"prerenderedAt":4322},["ShallowReactive",2],{"article-how-to-refine-ai-agent-workflow":3,"related-articles-how-to-refine-ai-agent-workflow":831},{"id":4,"title":5,"author":6,"body":7,"category":802,"description":803,"extension":804,"featured":805,"heroImage":806,"meta":807,"navigation":805,"path":808,"publishedAt":809,"readingTime":810,"relatedAgents":811,"relatedArticles":815,"relatedWorkflows":819,"searchIntent":822,"seo":823,"stem":824,"topics":825,"updatedAt":809,"visual":829,"__hash__":830},"articles\u002Farticles\u002Fhow-to-refine-ai-agent-workflow.md","How to refine an AI agent workflow: best practices after the first working version","StackOS team",{"type":8,"value":9,"toc":790},"minimark",[10,14,17,20,25,28,37,40,43,46,50,53,75,78,81,84,88,91,94,97,108,111,114,117,137,140,144,147,150,177,180,183,186,189,290,293,303,306,310,313,391,394,467,475,478,481,485,488,581,584,587,590,594,597,600,614,617,620,624,627,630,633,653,656,659,663,666,747,751,754,757,783,786],[11,12,13],"p",{},"To refine an AI agent workflow, I do not start by personally reviewing every step. I ask an agent to manage the refinement. That agent sends subagents through the workflow as first-time operators, collects their firsthand feedback, and questions them after each run about friction, decisions, missing context, and workarounds.",[11,15,16],{},"The orchestrator then gates that feedback. It separates consequential defects from normal agent friction, traces accepted findings to the correct layer, and proposes the smallest reusable fix. After the change, fresh agents run the workflow again. We stop when they can reach the accepted outcome reliably—not when nobody can imagine another improvement.",[11,18,19],{},"This combines two kinds of evidence: what the workflow produced and what the agents experienced while producing it. The second is easy to miss when the operator becomes the only reviewer.",[21,22,24],"h2",{"id":23},"refinement-starts-after-the-workflow-works","Refinement starts after the workflow works",[11,26,27],{},"Design and refinement solve different problems.",[11,29,30,31,36],{},"When we ",[32,33,35],"a",{"href":34},"\u002Flibrary\u002Farticles\u002Fhow-to-build-ai-agent-workflow","define an AI agent workflow",", we start with the problem, the desired outcome, the orchestration model, the specialist responsibilities, and the terminal condition. The first useful milestone is a workflow that can complete a representative task.",[11,38,39],{},"Refinement begins after that milestone. The question is no longer, “What workflow should we build?” It is, “What did agents actually experience when they used it, and which changes would make the accepted outcome more reliable?”",[11,41,42],{},"Keeping that boundary explicit prevents a common mistake: redesigning the workflow before understanding the failure. A weak result may come from an ambiguous acceptance criterion, missing context, a poor tool interface, a stale runtime contract, a specialist mistake, or a temporary environment problem. Those causes do not call for the same fix.",[11,44,45],{},"More agents can generate more evidence, but more agents, review rounds, and instructions are not themselves proof of a better workflow. Their value is in giving the refinement orchestrator independent runs to compare.",[21,47,49],{"id":48},"preserve-the-accepted-baseline","Preserve the accepted baseline",[11,51,52],{},"Before changing anything, write down the state you are trying to preserve. At minimum, keep:",[54,55,56,60,63,66,69,72],"ul",{},[57,58,59],"li",{},"the operator’s problem and intended outcome;",[57,61,62],{},"the current scope and hard constraints;",[57,64,65],{},"the acceptance criteria;",[57,67,68],{},"the terminal condition;",[57,70,71],{},"one representative task the workflow has already completed;",[57,73,74],{},"the evidence that showed it completed successfully.",[11,76,77],{},"This baseline is the control for the next run. Without it, “improvement” becomes whatever the latest reviewer prefers.",[11,79,80],{},"The terminal condition should describe observable state. “The article is good” is not enough. “The draft exists, required sections are present, material claims have supporting evidence or an explicit unresolved status, blocking review findings are repaired, and sanitization checks pass” gives the orchestrator something concrete to evaluate.",[11,82,83],{},"It also makes the stopping rule visible. A reviewer can always imagine another improvement. The workflow should not remain open merely because more polish is possible.",[21,85,87],{"id":86},"let-agents-test-the-workflow-as-first-time-operators","Let agents test the workflow as first-time operators",[11,89,90],{},"My preferred setup has one refinement agent coordinating several independent workflow runs. The coordinating agent is not there to perform all the work itself. It gives subagents a realistic task, lets them use the workflow, and preserves what happened.",[11,92,93],{},"The runners should not be told which failure you expect them to find. That primes them to confirm the diagnosis. Give them the kind of instruction a real user would give, with only the context a normal run would have.",[11,95,96],{},"A test instruction can be this small:",[98,99,105],"pre",{"className":100,"code":102,"language":103,"meta":104},[101],"language-text","Use the project workflow to produce the requested article.\nWork as if this is your first time using it.\nUse the context and tools the workflow provides.\nDo not change the workflow while running it.\nStop when its completion conditions are met or when you are genuinely blocked.\n","text","",[106,107,102],"code",{"__ignoreMap":104},[11,109,110],{},"The actual topic or task belongs above that instruction. The important part is what is absent: no hint about the suspected defect, no private debugging history, and no checklist that tells the runner what feedback to return.",[11,112,113],{},"For an inexpensive workflow, I usually want more than one run. Two or three subagents are often enough to expose whether a finding repeats. They can receive different representative tasks, or the same task when consistency is the concern. For higher-cost work, one runner plus a targeted replay may be sufficient.",[11,115,116],{},"The refinement agent should collect a compact receipt from every run:",[54,118,119,122,125,128,131,134],{},[57,120,121],{},"the user-like instruction the runner received;",[57,123,124],{},"the workflow and version it used;",[57,126,127],{},"the final outcome and whether the terminal condition passed;",[57,129,130],{},"important tool calls, retries, and recovery actions;",[57,132,133],{},"any point where state advanced incorrectly;",[57,135,136],{},"the runner’s post-run feedback.",[11,138,139],{},"This is not the operator watching every tool call. The operator delegates the observation work and receives a synthesized decision packet.",[21,141,143],{"id":142},"interview-the-agents-after-they-finish","Interview the agents after they finish",[11,145,146],{},"The run trace shows what the agent did. It does not always show where the agent hesitated, which assumption it made, or what it wished the workflow had supplied. I ask those questions after the run, while the agent still has the experience in context.",[11,148,149],{},"Useful questions are concrete:",[151,152,153,156,159,162,165,168,171,174],"ol",{},[57,154,155],{},"Where did you hesitate or have to investigate before you could continue?",[57,157,158],{},"Which decision did you make that the workflow did not clearly resolve?",[57,160,161],{},"What context did you need but not receive at the point of use?",[57,163,164],{},"Was any tool difficult to find, understand, or call correctly?",[57,166,167],{},"What workaround did you use?",[57,169,170],{},"Did the friction threaten the final outcome, or did it only add effort?",[57,172,173],{},"What part of the workflow was clearer than expected?",[57,175,176],{},"If you changed one generic thing for the next agent, what would it be? What would you leave alone?",[11,178,179],{},"The last question matters. Agents can identify useful friction without concluding that every friction needs a fix.",[11,181,182],{},"The coordinator can run these as separate debrief sessions. Keeping the runners independent until after their answers are recorded avoids early consensus. One agent may report missing context while another finds the context immediately but struggles with the tool contract. That difference is part of the signal.",[11,184,185],{},"If there are several runners, the coordinating agent can spawn a debrief subagent to hold a short feedback session with each one and normalize the answers into the same fields. That subagent collects evidence; it does not decide what the workflow should change. The coordinator keeps the gate.",[11,187,188],{},"A feedback record does not need to be long:",[98,190,194],{"className":191,"code":192,"language":193,"meta":104,"style":104},"language-yaml shiki shiki-themes github-light github-dark","run: workflow-refinement-trial-02\noutcome: passed\nfriction: \"I had to inspect several broad documents before finding the step contract\"\ndecision_made: \"Used the targeted step packet as the source of truth\"\nworkaround: \"Recovered with a scoped lookup\"\nconsequence: latency_only\nsuggested_change: \"Make the targeted packet easier to discover\"\nrunner_confidence: medium\n","yaml",[106,195,196,213,224,235,246,257,268,279],{"__ignoreMap":104},[197,198,201,205,209],"span",{"class":199,"line":200},"line",1,[197,202,204],{"class":203},"s9eBZ","run",[197,206,208],{"class":207},"sVt8B",": ",[197,210,212],{"class":211},"sZZnC","workflow-refinement-trial-02\n",[197,214,216,219,221],{"class":199,"line":215},2,[197,217,218],{"class":203},"outcome",[197,220,208],{"class":207},[197,222,223],{"class":211},"passed\n",[197,225,227,230,232],{"class":199,"line":226},3,[197,228,229],{"class":203},"friction",[197,231,208],{"class":207},[197,233,234],{"class":211},"\"I had to inspect several broad documents before finding the step contract\"\n",[197,236,238,241,243],{"class":199,"line":237},4,[197,239,240],{"class":203},"decision_made",[197,242,208],{"class":207},[197,244,245],{"class":211},"\"Used the targeted step packet as the source of truth\"\n",[197,247,249,252,254],{"class":199,"line":248},5,[197,250,251],{"class":203},"workaround",[197,253,208],{"class":207},[197,255,256],{"class":211},"\"Recovered with a scoped lookup\"\n",[197,258,260,263,265],{"class":199,"line":259},6,[197,261,262],{"class":203},"consequence",[197,264,208],{"class":207},[197,266,267],{"class":211},"latency_only\n",[197,269,271,274,276],{"class":199,"line":270},7,[197,272,273],{"class":203},"suggested_change",[197,275,208],{"class":207},[197,277,278],{"class":211},"\"Make the targeted packet easier to discover\"\n",[197,280,282,285,287],{"class":199,"line":281},8,[197,283,284],{"class":203},"runner_confidence",[197,286,208],{"class":207},[197,288,289],{"class":211},"medium\n",[11,291,292],{},"The refinement agent can now compare the reported experience with the trace and final state. This is more useful than asking a reviewer to critique the workflow in the abstract.",[11,294,295,296,302],{},"Anthropic’s ",[32,297,301],{"href":298,"rel":299},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fdemystifying-evals-for-ai-agents",[300],"nofollow","guide to agent evaluations"," provides useful language for separating a task, trial, trajectory, and outcome. I use that distinction as supporting structure. The practical method is still to let agents perform realistic work and then ask them what the trace does not reveal.",[11,304,305],{},"One successful replay shows that the path is possible, not that it is consistent. Use more trials when consistency matters, scaled to the risk and cost of failure.",[21,307,309],{"id":308},"synthesize-the-feedback-without-accepting-all-of-it","Synthesize the feedback without accepting all of it",[11,311,312],{},"After the runs and debriefs, the refinement agent has more feedback than should enter delivery. Its job is to compare accounts, connect them to receipts, and classify the findings before suggesting a change.",[314,315,316,332],"table",{},[317,318,319],"thead",{},[320,321,322,326,329],"tr",{},[323,324,325],"th",{},"Finding",[323,327,328],{},"Meaning",[323,330,331],{},"What to do",[333,334,335,347,358,369,380],"tbody",{},[320,336,337,341,344],{},[338,339,340],"td",{},"Blocking defect",[338,342,343],{},"The workflow cannot meet an accepted criterion, violates a hard constraint, or advances state incorrectly.",[338,345,346],{},"Fix before accepting the run.",[320,348,349,352,355],{},[338,350,351],{},"Bounded repair",[338,353,354],{},"A specific correction inside the accepted scope would restore the outcome.",[338,356,357],{},"Route the smallest repair to the responsible layer.",[320,359,360,363,366],{},[338,361,362],{},"Normal friction",[338,364,365],{},"The agent needed reasonable investigation or recovery but still reached the outcome safely.",[338,367,368],{},"Record only if useful; do not change the workflow by default.",[320,370,371,374,377],{},[338,372,373],{},"Preference",[338,375,376],{},"A different approach may be nicer, but the accepted outcome still passes.",[338,378,379],{},"Keep out of delivery unless the operator changes the plan.",[320,381,382,385,388],{},[338,383,384],{},"Scope change",[338,386,387],{},"The suggestion changes the goal, audience, capability, or delivery boundary.",[338,389,390],{},"Treat it as a separate decision, not refinement of the current run.",[11,392,393],{},"The synthesis can be a simple table:",[314,395,396,415],{},[317,397,398],{},[320,399,400,403,406,409,412],{},[323,401,402],{},"Observation",[323,404,405],{},"Seen in",[323,407,408],{},"Outcome effect",[323,410,411],{},"Likely layer",[323,413,414],{},"Gate decision",[333,416,417,434,451],{},[320,418,419,422,425,428,431],{},[338,420,421],{},"Required context was absent at the point of use",[338,423,424],{},"3 of 3 runs",[338,426,427],{},"One blocked, two guessed",[338,429,430],{},"Context and handoff",[338,432,433],{},"Admit as a blocker",[320,435,436,439,442,445,448],{},[338,437,438],{},"Runner read more broadly than expected",[338,440,441],{},"1 of 3 runs",[338,443,444],{},"Added latency; outcome passed",[338,446,447],{},"Normal task friction",[338,449,450],{},"Record, do not change",[320,452,453,456,459,462,464],{},[338,454,455],{},"Reviewer preferred a different article structure",[338,457,458],{},"1 review",[338,460,461],{},"No accepted criterion failed",[338,463,373],{},[338,465,466],{},"Keep out of delivery",[11,468,469,470,474],{},"This is where the orchestrator acts as a gatekeeper. Runners and reviewers should report what they find, but ",[32,471,473],{"href":472},"\u002Flibrary\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback","feedback is not automatically delivery scope",". The orchestrator admits findings only when they protect the outcome that was already agreed.",[11,476,477],{},"We saw this distinction during a cold-start replay of one of our own workflows. The agent did some broad reading that added latency. It also found the relevant path, recovered with targeted inspection, and reached the terminal condition. The friction was real, but it did not block the goal or make the result unsafe. Rewriting the workflow around that single inconvenience would have been a weak use of the evidence.",[11,479,480],{},"Friction will always exist in work performed by agents. The useful question is whether it exposes a repeatable failure with a meaningful consequence.",[21,482,484],{"id":483},"trace-the-issue-to-the-correct-layer","Trace the issue to the correct layer",[11,486,487],{},"A symptom appears where the agent encounters it. The cause may sit somewhere else.",[314,489,490,503],{},[317,491,492],{},[320,493,494,497,500],{},[323,495,496],{},"Layer",[323,498,499],{},"Typical signal",[323,501,502],{},"Appropriate refinement",[333,504,505,516,527,537,548,559,570],{},[320,506,507,510,513],{},[338,508,509],{},"Intent and acceptance",[338,511,512],{},"Different agents cannot agree on what done means.",[338,514,515],{},"Clarify the outcome, constraint, or terminal condition.",[320,517,518,521,524],{},[338,519,520],{},"Workflow contract",[338,522,523],{},"Steps overlap, dependencies are unclear, or outputs do not hand off cleanly.",[338,525,526],{},"Repair step boundaries, dependencies, or output contracts.",[320,528,529,531,534],{},[338,530,430],{},[338,532,533],{},"A specialist must rediscover facts the prior step already knew.",[338,535,536],{},"Pass a smaller, explicit context packet with source refs and expectations.",[320,538,539,542,545],{},[338,540,541],{},"Tool surface",[338,543,544],{},"The right operation exists but is hard to find or poorly described.",[338,546,547],{},"Improve tool selection, names, schemas, or usage guidance.",[320,549,550,553,556],{},[338,551,552],{},"Runtime enforcement",[338,554,555],{},"Invalid output advances state, stale contracts remain active, or grants do not match the step.",[338,557,558],{},"Fix validation, synchronization, permissions, or state transitions in code.",[320,560,561,564,567],{},[338,562,563],{},"Specialist behavior",[338,565,566],{},"The inputs and tools are sufficient, but the agent applies weak judgment or produces poor work.",[338,568,569],{},"Refine the role, examples, evaluation criteria, or model choice.",[320,571,572,575,578],{},[338,573,574],{},"Environment",[338,576,577],{},"A provider, credential, network, or local service is temporarily unavailable.",[338,579,580],{},"Repair the environment or define bounded recovery; do not rewrite the workflow first.",[11,582,583],{},"This layer map prevents prompt-shaped fixes for code-shaped problems.",[11,585,586],{},"In one content workflow run, a step returned output that did not match its declared result schema. At first glance, that could look like an agent-quality problem. Investigation showed two runtime causes: an updated workflow definition had not refreshed a cached generated contract, and the result schema existed but was not enforced before state mutation.",[11,588,589],{},"We fixed the reusable layer. Contract generation became version-aware, and result validation moved in front of the state transition. In the next verification, malformed output was rejected without advancing the workflow; corrected output completed the step. The important improvement was not a new instruction telling one agent to “be more careful.” It was enforcement of an invariant that every agent should be able to rely on.",[21,591,593],{"id":592},"repair-the-generic-cause-one-change-at-a-time","Repair the generic cause, one change at a time",[11,595,596],{},"Once the layer is clear, make the smallest change that explains the evidence.",[11,598,599],{},"A good refinement should answer four questions:",[151,601,602,605,608,611],{},[57,603,604],{},"What observed failure are we correcting?",[57,606,607],{},"Which accepted criterion did it threaten?",[57,609,610],{},"Why does the cause belong to this layer?",[57,612,613],{},"What replay would distinguish a real fix from a one-off success?",[11,615,616],{},"Avoid hard-coding the example that exposed the problem. If one research query fails because the workflow cannot carry source context between steps, do not add that query to a prompt. Repair the handoff contract. If one malformed result advances state, do not describe the correct JSON more forcefully. Validate the result mechanically.",[11,618,619],{},"Change one layer when possible, then rerun. Simultaneous edits to the prompt, tools, step structure, and runtime may produce a passing result, but they make it difficult to know which change mattered or which one introduced a regression.",[21,621,623],{"id":622},"rerun-with-fresh-agents","Rerun with fresh agents",[11,625,626],{},"A refinement is not verified only by the agent that already knows the investigation.",[11,628,629],{},"Start fresh subagents with the kind of request the workflow is meant to receive. They should rely on the workflow’s own context, tools, handoffs, and success criteria. They should not receive the private explanation used to diagnose the previous failure.",[11,631,632],{},"Check both the result and the path:",[54,634,635,638,641,644,647,650],{},[57,636,637],{},"Did the workflow reach the required environment state?",[57,639,640],{},"Did invalid intermediate output fail safely?",[57,642,643],{},"Did each specialist receive enough context to act without avoidable investigation?",[57,645,646],{},"Did the orchestrator keep preferences and scope changes out of delivery?",[57,648,649],{},"Did recovery preserve the accepted outcome?",[57,651,652],{},"Did the run stop when the terminal condition became true?",[11,654,655],{},"Then repeat the debrief. Ask the same questions so the before-and-after feedback is comparable. If the agents still report the same consequential guess or workaround, the change did not repair the operating experience even if the output happened to pass once.",[11,657,658],{},"For repeatable failure modes, turn the observed case into a regression task. Anthropic recommends starting eval sets from the manual checks and real failures teams already use. That keeps evaluation close to actual behavior instead of inventing abstract tests that are easy to pass and hard to trust.",[21,660,662],{"id":661},"ai-agent-workflow-best-practices-for-refinement","AI agent workflow best practices for refinement",[11,664,665],{},"The following practices are the ones I would carry into another workflow:",[151,667,668,675,681,687,693,699,705,711,717,723,729,741],{},[57,669,670,674],{},[671,672,673],"strong",{},"Delegate the refinement process to an agent."," The operator defines the goal and decision boundary; the refinement agent coordinates trials, debriefs, synthesis, and verification.",[57,676,677,680],{},[671,678,679],{},"Send independent subagents through the workflow."," Give them realistic, minimally primed instructions and let them work from the workflow’s own context.",[57,682,683,686],{},[671,684,685],{},"Ask questions after each run."," Collect friction, hidden decisions, missing context, tool confusion, workarounds, and what the runner would leave unchanged.",[57,688,689,692],{},[671,690,691],{},"Preserve both receipts and firsthand accounts."," The trace explains what happened; the debrief explains how the operating experience felt to the agent.",[57,694,695,698],{},[671,696,697],{},"Compare runs before diagnosing."," Repeated findings are stronger signals than one agent’s preference, but a single safety or state-integrity failure can still be blocking.",[57,700,701,704],{},[671,702,703],{},"Freeze the accepted outcome."," Keep the goal, constraints, acceptance criteria, and terminal condition stable during the refinement cycle.",[57,706,707,710],{},[671,708,709],{},"Classify every finding."," Distinguish blockers, repairs, normal friction, preferences, and scope changes before admitting work.",[57,712,713,716],{},[671,714,715],{},"Diagnose the layer before choosing the fix."," Do not solve runtime failures with longer prompts or specialist failures with more orchestration.",[57,718,719,722],{},[671,720,721],{},"Repair reusable causes."," Prefer contracts, validation, clearer context, and better tool interfaces over examples hard-coded for one run.",[57,724,725,728],{},[671,726,727],{},"Rerun with fresh agents and the same debrief."," Verification should succeed without hidden knowledge from the debugging session, and the reported friction should materially improve.",[57,730,731,734,735,740],{},[671,732,733],{},"Set a stopping rule."," Microsoft’s ",[32,736,739],{"href":737,"rel":738},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fazure\u002Farchitecture\u002Fai-ml\u002Fguide\u002Fai-agent-design-patterns",[300],"maker-checker guidance"," calls for clear acceptance criteria and an iteration cap so refinement loops do not run indefinitely.",[57,742,743,746],{},[671,744,745],{},"Accept normal friction."," Change the workflow when evidence shows a meaningful, repeatable consequence—not simply because another improvement is imaginable.",[21,748,750],{"id":749},"stop-at-reliable-not-frictionless","Stop at reliable, not frictionless",[11,752,753],{},"The goal of workflow refinement is not to remove judgment, variability, or every moment of investigation. It is to make the accepted outcome reachable, inspectable, and recoverable under realistic conditions.",[11,755,756],{},"That gives the refinement orchestrator a bounded loop:",[151,758,759,762,765,768,771,774,777,780],{},[57,760,761],{},"preserve the baseline;",[57,763,764],{},"send subagents through representative tasks;",[57,766,767],{},"preserve each trajectory and outcome;",[57,769,770],{},"debrief the runners;",[57,772,773],{},"compare and classify the findings;",[57,775,776],{},"repair the smallest reusable cause;",[57,778,779],{},"rerun with fresh agents and repeat the questions;",[57,781,782],{},"stop when the terminal condition is reliably true.",[11,784,785],{},"If a workflow still reaches the goal safely and a fresh agent can work around minor friction, that may be enough. Polish should improve delivery. It should not become a reason to keep the workflow open forever.",[787,788,789],"style",{},"html pre.shiki code .s9eBZ, html code.shiki .s9eBZ{--shiki-default:#22863A;--shiki-dark:#85E89D}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}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 .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":104,"searchDepth":215,"depth":215,"links":791},[792,793,794,795,796,797,798,799,800,801],{"id":23,"depth":215,"text":24},{"id":48,"depth":215,"text":49},{"id":86,"depth":215,"text":87},{"id":142,"depth":215,"text":143},{"id":308,"depth":215,"text":309},{"id":483,"depth":215,"text":484},{"id":592,"depth":215,"text":593},{"id":622,"depth":215,"text":623},{"id":661,"depth":215,"text":662},{"id":749,"depth":215,"text":750},"AI operations","A practical method for using agents, independent workflow runs, and post-run debriefs to refine AI workflows without scope drift.","md",true,null,{},"\u002Farticles\u002Fhow-to-refine-ai-agent-workflow","2026-07-12","12 min read",[812,813,814],"branding-claim-auditor","branding-voice-reviewer","stackos-sdlc-delivery-reviewer",[816,817,818],"how-to-build-ai-agent-workflow","ai-agent-experience","how-ai-orchestrators-triage-feedback",[820,821],"branding-content-production","engineering-tracked-delivery","Learn how to test, refine, and polish an AI agent workflow after the first version works",{"title":5,"description":803},"articles\u002Fhow-to-refine-ai-agent-workflow",[826,827,828],"AI agent workflows","workflow refinement","agent evaluation","workflow","IJUZCaIRsdc_bwHYy3kmxmuqGmTwbUOe6KpWSxNsKqE",[832,1137,1518,2060,2875,3142,3439,3673,3858,4034],{"id":833,"title":834,"author":6,"body":835,"category":802,"description":1119,"extension":804,"featured":805,"heroImage":806,"meta":1120,"navigation":805,"path":1121,"publishedAt":809,"readingTime":1122,"relatedAgents":1123,"relatedArticles":1126,"relatedWorkflows":1128,"searchIntent":1129,"seo":1130,"stem":1131,"topics":1132,"updatedAt":809,"visual":847,"__hash__":1136},"articles\u002Farticles\u002Fai-workflow-automation.md","AI workflow automation: automate the rules, not the judgment",{"type":8,"value":836,"toc":1111},[837,840,843,849,853,856,859,862,865,868,871,875,894,897,900,920,923,927,930,933,936,939,942,949,953,956,959,1051,1054,1057,1061,1064,1067,1070,1078,1082,1085,1102,1105,1108],[11,838,839],{},"AI workflow automation combines two different kinds of control. Code should enforce the rules that must hold every time: state, dependencies, permissions, schemas, receipts, and stopping conditions. An agent should decide what cannot be known until the work is underway: which evidence matters, whether the plan should adapt, and which feedback belongs in the result.",[11,841,842],{},"Treating the whole workflow as either a fixed automation or an autonomous agent misses the useful middle. The practical design question is not, “How much AI can we add?” It is, “Which decisions should still require judgment?”",[844,845],"article-concept-visual",{"caption":846,"mode":847,"title":848},"The runtime enforces invariants. Agents make evidence-dependent decisions. People enter for missing intent or consequential choices.","connections","One workflow, three kinds of control",[21,850,852],{"id":851},"a-failure-that-a-better-prompt-could-not-fix","A failure that a better prompt could not fix",[11,854,855],{},"We ran into a useful example while refining our own content workflow.",[11,857,858],{},"The workflow definition had changed, but part of the running system still held an older generation of the plugin and resource contracts. The agent could see the current content workflow while receiving an older schema for the record it needed to write. One part of the system described the right job; another enforced the wrong shape.",[11,860,861],{},"There was a second gap. Each workflow step already declared an output contract, but a step could still be recorded as successful without proving that its result matched that contract.",[11,863,864],{},"Neither problem belonged in the prompt. Telling the agent to “use the latest schema” would not make two runtime generations consistent. Telling it to “return every required field” would not make success verifiable.",[11,866,867],{},"We moved both responsibilities into the mechanical layer. Editable plugin manifests now carry a source-generation fingerprint, and the catalog resynchronizes when that generation changes. Successful step results are validated against their frozen JSON Schema before any lifecycle transition is persisted. If a required field is missing, the step remains running and the error points to the exact field that needs repair.",[11,869,870],{},"We then exercised the failure path live: an incomplete result was rejected without advancing the step, and the corrected result completed it. This is bounded first-party evidence from one implementation, not proof that the same architecture fits every system. The lesson is narrower: if correctness depends on an invariant, the system should enforce it without asking the model to remember.",[21,872,874],{"id":873},"put-stable-rules-in-the-mechanical-layer","Put stable rules in the mechanical layer",[11,876,877,882,883,887,888,893],{},[32,878,881],{"href":879,"rel":880},"https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fbuilding-effective-agents",[300],"Anthropic distinguishes workflows from agents"," by who controls the path: workflows use predefined code paths, while agents dynamically direct their process and tool use. Microsoft’s ",[32,884,886],{"href":737,"rel":885},[300],"orchestration pattern guidance"," and Google Cloud’s ",[32,889,892],{"href":890,"rel":891},"https:\u002F\u002Fdocs.cloud.google.com\u002Farchitecture\u002Fchoose-design-pattern-agentic-ai-system",[300],"agentic design-pattern guide"," make a similar distinction between predictable sequences and dynamic orchestration.",[11,895,896],{},"That distinction is useful inside one workflow, not only when choosing an architecture for the whole system.",[11,898,899],{},"The mechanical layer should own conditions whose answer does not improve with another model call:",[54,901,902,905,908,911,914,917],{},[57,903,904],{},"A dependent step cannot start before its prerequisite finishes.",[57,906,907],{},"A research step can read sources but cannot publish.",[57,909,910],{},"A successful result must contain the fields and types its consumer expects.",[57,912,913],{},"A completed external action needs a receipt the workflow can inspect before retrying.",[57,915,916],{},"A packet-only request must stop before publication.",[57,918,919],{},"The current state and evidence refs must survive the conversation that produced them.",[11,921,922],{},"These controls reduce ambiguity without reducing useful autonomy. The agent no longer spends judgment on whether a required field is optional this time or whether “packet only” might permit a deployment. It can use that judgment on the work itself.",[21,924,926],{"id":925},"keep-evidence-dependent-choices-with-the-agent","Keep evidence-dependent choices with the agent",[11,928,929],{},"Some decisions look repetitive but do not have a stable answer.",[11,931,932],{},"In this article’s workflow, the interview step was always present, but the interview was not mandatory. The agent had to inspect the current voice guide, prior pieces, recorded operator statements, and the new topic. Those sources already captured the relevant judgment, so the interview was skipped with a reason and a list of perspectives the article could not claim.",[11,934,935],{},"Hard-coding “always interview” would add ceremony. Hard-coding “never interview” would remove a source when first-hand experience was actually missing. The stable rule is that the decision must be made and explained. The answer remains contextual.",[11,937,938],{},"The same boundary applies to research and review. A schema can require a source ledger; it cannot decide which source resolves a contradiction. A workflow can require independent claim and voice review; it should not automatically turn every reviewer preference into another delivery cycle.",[11,940,941],{},"The orchestrator owns that gate. It can accept a supported blocker, send a specific defect back for repair, retain a preference as advice, and reject an unsupported or out-of-scope finding. Review produces evidence. It does not acquire authority over the original goal merely because it happened later.",[11,943,944,945,948],{},"This is where an ",[32,946,947],{"href":34},"AI agent workflow"," differs from a long automation script. The contract defines the operating boundary. Reasoning handles the parts whose answer depends on meaning, evidence, or changed conditions.",[21,950,952],{"id":951},"one-workflow-can-mix-all-three-control-modes","One workflow can mix all three control modes",[11,954,955],{},"Our content workflow follows a visible sequence: decide on interview scope, collect evidence, choose an angle, draft, review claims and voice, check disclosure risk, render the selected channel packet, preserve the final record, and stop or publish according to the request.",[11,957,958],{},"The sequence and handoffs are deterministic. The work inside them is not.",[314,960,961,974],{},[317,962,963],{},[320,964,965,968,971],{},[323,966,967],{},"Responsibility",[323,969,970],{},"Best owner",[323,972,973],{},"Why",[333,975,976,987,998,1009,1019,1030,1040],{},[320,977,978,981,984],{},[338,979,980],{},"Require a source ledger and claim map",[338,982,983],{},"Runtime contract",[338,985,986],{},"The requirement is stable and machine-checkable.",[320,988,989,992,995],{},[338,990,991],{},"Decide whether existing evidence is sufficient",[338,993,994],{},"Agent",[338,996,997],{},"The answer depends on the topic, source quality, and claims being considered.",[320,999,1000,1003,1006],{},[338,1001,1002],{},"Prevent drafting before research completes",[338,1004,1005],{},"Workflow state",[338,1007,1008],{},"The dependency should hold on every run.",[320,1010,1011,1014,1016],{},[338,1012,1013],{},"Choose the article angle",[338,1015,994],{},[338,1017,1018],{},"Reader value and evidence fit require interpretation.",[320,1020,1021,1024,1027],{},[338,1022,1023],{},"Decide whether a review finding changes delivery",[338,1025,1026],{},"Orchestrator",[338,1028,1029],{},"The finding must be tested against the accepted goal and evidence.",[320,1031,1032,1035,1037],{},[338,1033,1034],{},"Prevent a packet-only run from publishing",[338,1036,983],{},[338,1038,1039],{},"Execution intent is an explicit boundary, not a suggestion.",[320,1041,1042,1045,1048],{},[338,1043,1044],{},"Clarify a missing destination or sensitive disclosure choice",[338,1046,1047],{},"Person",[338,1049,1050],{},"Guessing would materially change the requested action or public boundary.",[11,1052,1053],{},"The person is not a rubber stamp between every row. Human participation belongs where the system lacks legitimate authority or information: the goal is ambiguous, evidence conflicts on a consequential point, disclosure ownership is unclear, or an external action needs a choice that was never supplied.",[11,1055,1056],{},"That is different from inserting approval because AI is involved. A mandatory checkpoint can be appropriate for a risky action. It is not a substitute for a clear workflow.",[21,1058,1060],{"id":1059},"use-failure-location-to-improve-the-boundary","Use failure location to improve the boundary",[11,1062,1063],{},"When an AI workflow fails, ask which layer was forced to compensate.",[11,1065,1066],{},"If the agent searched for a source the workflow already knew, context selection failed. If it guessed which account or destination to use, authority was unresolved. If it returned a malformed packet and the system accepted it, validation failed. If a reviewer’s optional rewrite expanded the task, feedback adjudication failed. If the system stopped on missing operator intent and asked one focused question, the boundary may have worked exactly as intended.",[11,1068,1069],{},"This makes ordinary friction useful evidence. A workflow does not need to eliminate every search, retry, or clarification. It needs to keep recovery local and prevent that friction from turning into silent drift.",[11,1071,1072,1073,1077],{},"The ",[32,1074,1076],{"href":1075},"\u002Flibrary\u002Farticles\u002Fai-agent-experience","agent experience"," article develops that point at the claimed-step level. The automation boundary is the system-level version: decide which uncertainty the agent should resolve and which uncertainty the system should remove before the step begins.",[21,1079,1081],{"id":1080},"a-compact-automation-boundary-test","A compact automation-boundary test",[11,1083,1084],{},"For each responsibility in a workflow, ask:",[151,1086,1087,1090,1093,1096,1099],{},[57,1088,1089],{},"Does the rule need to hold on every valid run?",[57,1091,1092],{},"Can the result be checked without interpreting meaning?",[57,1094,1095],{},"Does the answer change with evidence or intermediate results?",[57,1097,1098],{},"Would a wrong guess change scope, expose data, spend money, or create an external side effect?",[57,1100,1101],{},"Can a failed attempt be repaired locally without replaying completed work?",[11,1103,1104],{},"Stable and machine-checkable responsibilities belong in code, schemas, state transitions, or scoped tool grants. Evidence-dependent responsibilities belong with a reasoning agent. Missing authority or a genuinely consequential choice belongs with the person who owns it.",[11,1106,1107],{},"The boundary will not be perfect on the first run. Ours was not. The useful signal was that a live failure identified two invariants the runtime had left to convention. We fixed those invariants mechanically and kept the editorial decisions with the agents.",[11,1109,1110],{},"That is the point of AI workflow automation: not to automate judgment away, but to stop wasting it on rules the system can already know.",{"title":104,"searchDepth":215,"depth":215,"links":1112},[1113,1114,1115,1116,1117,1118],{"id":851,"depth":215,"text":852},{"id":873,"depth":215,"text":874},{"id":925,"depth":215,"text":926},{"id":951,"depth":215,"text":952},{"id":1059,"depth":215,"text":1060},{"id":1080,"depth":215,"text":1081},"A practical way to decide what AI workflows should enforce in code, what agents should decide at runtime, and when a person genuinely needs to step in.",{},"\u002Farticles\u002Fai-workflow-automation","8 min read",[1124,1125,812],"branding-channel-strategist","branding-narrative-writer",[816,817,1127],"what-is-an-agentic-workflow",[820,821],"Learn how to automate AI workflows without hard-coding the judgment they need",{"title":834,"description":1119},"articles\u002Fai-workflow-automation",[1133,1134,1135],"AI workflow automation","agent orchestration","workflow architecture","ivj4k_-yJoUYW08VqRr6mbUEC2lYzjoWMWbJCgOnxvo",{"id":1138,"title":1139,"author":6,"body":1140,"category":802,"description":1503,"extension":804,"featured":805,"heroImage":806,"meta":1504,"navigation":805,"path":1505,"publishedAt":809,"readingTime":1122,"relatedAgents":1506,"relatedArticles":1507,"relatedWorkflows":1509,"searchIntent":1510,"seo":1511,"stem":1512,"topics":1513,"updatedAt":809,"visual":1516,"__hash__":1517},"articles\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback.md","How should an AI orchestrator triage feedback?",{"type":8,"value":1141,"toc":1494},[1142,1145,1148,1152,1155,1158,1161,1164,1175,1179,1182,1185,1203,1206,1209,1212,1216,1219,1279,1282,1285,1289,1292,1330,1333,1408,1411,1415,1418,1421,1424,1431,1434,1438,1441,1444,1447,1450,1454,1457,1460,1483,1486,1492],[11,1143,1144],{},"An AI orchestrator should treat reviewer feedback as evidence, not as an instruction. Its job is to test each finding against the accepted goal, evidence, constraints, and terminal condition, then classify it as a blocker, a repair, a preference, or out of scope. Only findings that protect the agreed outcome should enter delivery.",[11,1146,1147],{},"That gate does not weaken review. It gives review a boundary. Without one, a capable reviewer can always imagine another improvement, and a workflow that accepts every suggestion can keep moving without getting closer to done.",[21,1149,1151],{"id":1150},"why-reviewer-output-is-not-automatically-work","Why reviewer output is not automatically work",[11,1153,1154],{},"A reviewer has a deliberately narrow responsibility. A claim auditor looks for unsupported claims. A security reviewer looks for unsafe behavior. An editor looks for structural and voice problems. That narrowness makes the review useful, but it does not give the reviewer ownership of the whole plan.",[11,1156,1157],{},"The orchestrator has the wider view. It knows what the operator asked for, which constraints were accepted, what evidence is available, which changes have already been made, and what state counts as complete. It should consider a reviewer’s finding from that position.",[11,1159,1160],{},"We learned this while refining our own workflows. Independent reviews surfaced plausible improvements, and it was tempting to treat each one as a new requirement. The result was scope drift: work expanded beyond the plan we had agreed to finish. The individual suggestions were not necessarily bad. The failure was allowing the act of suggesting something to redefine delivery.",[11,1162,1163],{},"The correction was not to remove reviewers or make their instructions weaker. It was to make one responsibility explicit: reviewers report findings; the orchestrator decides which findings belong in the current delivery.",[11,1165,1166,1170,1171,1174],{},[32,1167,1169],{"href":879,"rel":1168},[300],"Anthropic’s evaluator-optimizer pattern"," makes evaluation criteria a condition for a useful review loop. Microsoft’s ",[32,1172,739],{"href":737,"rel":1173},[300]," similarly calls for clear acceptance criteria, an iteration cap, and defined fallback behavior. A review loop is controlled by criteria and a stopping rule, not by the mere existence of more feedback.",[21,1176,1178],{"id":1177},"start-with-an-accepted-plan","Start with an accepted plan",[11,1180,1181],{},"Feedback cannot be triaged against a vague intention such as “make it better.” The orchestrator needs a small accepted plan that remains stable while the work is underway.",[11,1183,1184],{},"At minimum, that plan should name:",[54,1186,1187,1190,1193,1196,1198,1200],{},[57,1188,1189],{},"the problem being solved;",[57,1191,1192],{},"the requested output and its scope;",[57,1194,1195],{},"the evidence and constraints that apply;",[57,1197,65],{},[57,1199,68],{},[57,1201,1202],{},"any decisions reserved for the operator.",[11,1204,1205],{},"This is not a demand for a long specification. A compact plan is often better because the orchestrator can apply it consistently. The important part is that a reviewer finding must point to something in that plan if it is going to change delivery.",[11,1207,1208],{},"Suppose the accepted outcome is a public article with supported material claims, the required sections, the current brand voice, and no sensitive internal details. “A material claim has no source” threatens an acceptance criterion. “The introduction would be more dramatic as a personal story” may be a reasonable editorial preference, but it does not necessarily threaten the outcome.",[11,1210,1211],{},"The orchestrator should not pretend those findings have equal weight.",[21,1213,1215],{"id":1214},"use-four-feedback-classes","Use four feedback classes",[11,1217,1218],{},"The following classification is a practical operating model, not an industry standard. Its value is that every category has a different consequence.",[314,1220,1221,1234],{},[317,1222,1223],{},[320,1224,1225,1228,1231],{},[323,1226,1227],{},"Class",[323,1229,1230],{},"What it means",[323,1232,1233],{},"Orchestrator action",[333,1235,1236,1247,1258,1268],{},[320,1237,1238,1241,1244],{},[338,1239,1240],{},"Blocker",[338,1242,1243],{},"The output cannot meet an accepted criterion, is materially false or unsafe, or violates a hard constraint.",[338,1245,1246],{},"Admit it into delivery and prevent completion until it is resolved or explicitly marked unresolved.",[320,1248,1249,1252,1255],{},[338,1250,1251],{},"Repair",[338,1253,1254],{},"A bounded correction is needed inside the agreed scope.",[338,1256,1257],{},"Route it to the responsible agent with the failed criterion and expected evidence.",[320,1259,1260,1262,1265],{},[338,1261,373],{},[338,1263,1264],{},"The suggestion is defensible, but the current output can meet the accepted outcome without it.",[338,1266,1267],{},"Record it if useful; do not reopen delivery by default.",[320,1269,1270,1273,1276],{},[338,1271,1272],{},"Out of scope",[338,1274,1275],{},"The suggestion changes the goal, adds a new capability, or introduces work not required by the accepted plan.",[338,1277,1278],{},"Reject it for this run or return it as a separate proposal. Do not create follow-up work automatically.",[11,1280,1281],{},"The distinction between a blocker and a repair is useful. A blocker describes the state of the output. A repair describes bounded work that may remove the blocker. Keeping them separate prevents a reviewer from prescribing a large solution when a smaller correction would satisfy the criterion.",[11,1283,1284],{},"Preferences also deserve an explicit category. Otherwise they tend to masquerade as defects. A preference can still be valuable, but “valuable” is not the same as “required now.”",[21,1286,1288],{"id":1287},"make-the-triage-decision-inspectable","Make the triage decision inspectable",[11,1290,1291],{},"The orchestrator does not need a complicated scoring system. It needs a repeatable sequence that exposes why a finding was accepted or rejected.",[151,1293,1294,1300,1306,1312,1318,1324],{},[57,1295,1296,1299],{},[671,1297,1298],{},"Restate the finding as a testable claim."," Replace “this section is weak” with the specific condition the reviewer believes has failed.",[57,1301,1302,1305],{},[671,1303,1304],{},"Identify the affected criterion."," Ask which accepted requirement, constraint, or terminal condition is threatened.",[57,1307,1308,1311],{},[671,1309,1310],{},"Check the evidence."," Confirm that the finding refers to the current output and has enough evidence to justify action.",[57,1313,1314,1317],{},[671,1315,1316],{},"Classify the finding."," Choose blocker, repair, preference, or out of scope.",[57,1319,1320,1323],{},[671,1321,1322],{},"Choose the smallest valid action."," Admit a blocker, route a repair, record a preference, or reject scope expansion.",[57,1325,1326,1329],{},[671,1327,1328],{},"Re-evaluate completion."," Decide whether the terminal condition is still unmet after the admitted findings are considered.",[11,1331,1332],{},"A useful finding record can stay compact:",[98,1334,1336],{"className":191,"code":1335,"language":193,"meta":104,"style":104},"finding: \"Two factual claims have no source\"\ncriterion: \"Material claims are supported or marked unresolved\"\nevidence: [\"paragraph-6\", \"paragraph-9\"]\nclassification: blocker\naction: \"Return to the writer for a bounded evidence repair\"\nstatus: admitted\n",[106,1337,1338,1348,1358,1378,1388,1398],{"__ignoreMap":104},[197,1339,1340,1343,1345],{"class":199,"line":200},[197,1341,1342],{"class":203},"finding",[197,1344,208],{"class":207},[197,1346,1347],{"class":211},"\"Two factual claims have no source\"\n",[197,1349,1350,1353,1355],{"class":199,"line":215},[197,1351,1352],{"class":203},"criterion",[197,1354,208],{"class":207},[197,1356,1357],{"class":211},"\"Material claims are supported or marked unresolved\"\n",[197,1359,1360,1363,1366,1369,1372,1375],{"class":199,"line":226},[197,1361,1362],{"class":203},"evidence",[197,1364,1365],{"class":207},": [",[197,1367,1368],{"class":211},"\"paragraph-6\"",[197,1370,1371],{"class":207},", ",[197,1373,1374],{"class":211},"\"paragraph-9\"",[197,1376,1377],{"class":207},"]\n",[197,1379,1380,1383,1385],{"class":199,"line":237},[197,1381,1382],{"class":203},"classification",[197,1384,208],{"class":207},[197,1386,1387],{"class":211},"blocker\n",[197,1389,1390,1393,1395],{"class":199,"line":248},[197,1391,1392],{"class":203},"action",[197,1394,208],{"class":207},[197,1396,1397],{"class":211},"\"Return to the writer for a bounded evidence repair\"\n",[197,1399,1400,1403,1405],{"class":199,"line":259},[197,1401,1402],{"class":203},"status",[197,1404,208],{"class":207},[197,1406,1407],{"class":211},"admitted\n",[11,1409,1410],{},"The important field is not a severity score. It is the connection between the finding and the accepted plan.",[21,1412,1414],{"id":1413},"keep-judgment-with-the-orchestrator-and-invariants-in-code","Keep judgment with the orchestrator and invariants in code",[11,1416,1417],{},"Feedback triage contains both mechanical and judgment-dependent work.",[11,1419,1420],{},"Code can require every finding to contain a criterion, evidence reference, classification, and status. It can prevent a dependent step from starting while an admitted blocker remains open. It can enforce an iteration limit and preserve the decision record.",[11,1422,1423],{},"Code cannot reliably decide whether a new suggestion protects the operator’s goal or quietly replaces it. That depends on the current evidence, tradeoffs, and intent. The orchestrator should make that judgment.",[11,1425,1426,1427,1430],{},"This follows the same boundary described in ",[32,1428,1133],{"href":1429},"\u002Flibrary\u002Farticles\u002Fai-workflow-automation",": enforce stable rules mechanically, but leave evidence-dependent choices with the agent responsible for the plan.",[11,1432,1433],{},"The reviewers should also remain independent. The writer should not silently grade its own claims, and the orchestrator should not rewrite findings to make them easier to dismiss. Specialists report what they observe. The orchestrator owns admission into delivery.",[21,1435,1437],{"id":1436},"do-not-turn-every-disagreement-into-human-approval","Do not turn every disagreement into human approval",[11,1439,1440],{},"Human input is useful when the workflow lacks something only the operator can supply: intent, authority, a disclosure decision, acceptance of consequential risk, or a real change in scope.",[11,1442,1443],{},"It is not necessary merely because two agents disagree. If the accepted plan already resolves the disagreement, the orchestrator should apply it. Requiring a person to approve every classification would move the gate without improving the decision.",[11,1445,1446],{},"Microsoft’s orchestration guidance distinguishes feedback that loops work back for refinement from approval that advances a workflow. That distinction matters. A content preference is not an authorization decision. A sensitive external action may be.",[11,1448,1449],{},"When a finding would materially change the accepted plan, the orchestrator should stop and present the choice rather than assume permission. That is not routine review. It is a new operator decision.",[21,1451,1453],{"id":1452},"stop-when-the-accepted-outcome-is-reached","Stop when the accepted outcome is reached",[11,1455,1456],{},"A workflow should finish when its terminal condition is true and no admitted blocker remains open. It should not wait until reviewers have no further ideas.",[11,1458,1459],{},"This gives the orchestrator a concrete stopping test:",[54,1461,1462,1465,1468,1471,1474,1477,1480],{},[57,1463,1464],{},"required output exists;",[57,1466,1467],{},"acceptance criteria pass;",[57,1469,1470],{},"material claims have evidence or an explicit unresolved status;",[57,1472,1473],{},"admitted blockers are repaired or deliberately escalated;",[57,1475,1476],{},"required safety and sanitization checks pass;",[57,1478,1479],{},"preferences and out-of-scope suggestions are not blocking delivery;",[57,1481,1482],{},"the iteration limit has not been exceeded.",[11,1484,1485],{},"If the iteration limit is reached with a blocker still open, the workflow should return the best preserved state, the failed criterion, and the next safe action. It should not hide the problem behind another review round.",[11,1487,1488,1489,1491],{},"The broader lesson is simple: feedback improves a workflow only when someone owns the decision to use it. In an ",[32,1490,947],{"href":34},", that owner is the orchestrator. Reviewers protect specific quality boundaries. The orchestrator protects the agreed outcome.",[787,1493,789],{},{"title":104,"searchDepth":215,"depth":215,"links":1495},[1496,1497,1498,1499,1500,1501,1502],{"id":1150,"depth":215,"text":1151},{"id":1177,"depth":215,"text":1178},{"id":1214,"depth":215,"text":1215},{"id":1287,"depth":215,"text":1288},{"id":1413,"depth":215,"text":1414},{"id":1436,"depth":215,"text":1437},{"id":1452,"depth":215,"text":1453},"A practical way for AI orchestrators to separate blocking findings from repairs, preferences, and scope drift without weakening review.",{},"\u002Farticles\u002Fhow-ai-orchestrators-triage-feedback",[812,813,814],[816,817,1508],"ai-workflow-automation",[820,821],"Learn how an AI orchestrator should evaluate reviewer feedback without allowing scope drift",{"title":1139,"description":1503},"articles\u002Fhow-ai-orchestrators-triage-feedback",[1514,1515,1134],"AI orchestrators","feedback triage","roles","HDr0ZlW1pdujvJsGEnMW9-veloEebIRKk-K7iA-CGFg",{"id":4,"title":5,"author":6,"body":1519,"category":802,"description":803,"extension":804,"featured":805,"heroImage":806,"meta":2054,"navigation":805,"path":808,"publishedAt":809,"readingTime":810,"relatedAgents":2055,"relatedArticles":2056,"relatedWorkflows":2057,"searchIntent":822,"seo":2058,"stem":824,"topics":2059,"updatedAt":809,"visual":829,"__hash__":830},{"type":8,"value":1520,"toc":2042},[1521,1523,1525,1527,1529,1531,1535,1537,1539,1541,1543,1545,1559,1561,1563,1565,1567,1569,1571,1573,1578,1580,1582,1584,1598,1600,1602,1604,1606,1624,1626,1628,1630,1632,1700,1702,1707,1709,1711,1713,1767,1769,1823,1827,1829,1831,1833,1835,1905,1907,1909,1911,1913,1915,1917,1927,1929,1931,1933,1935,1937,1939,1953,1955,1957,1959,1961,2014,2016,2018,2020,2038,2040],[11,1522,13],{},[11,1524,16],{},[11,1526,19],{},[21,1528,24],{"id":23},[11,1530,27],{},[11,1532,30,1533,36],{},[32,1534,35],{"href":34},[11,1536,39],{},[11,1538,42],{},[11,1540,45],{},[21,1542,49],{"id":48},[11,1544,52],{},[54,1546,1547,1549,1551,1553,1555,1557],{},[57,1548,59],{},[57,1550,62],{},[57,1552,65],{},[57,1554,68],{},[57,1556,71],{},[57,1558,74],{},[11,1560,77],{},[11,1562,80],{},[11,1564,83],{},[21,1566,87],{"id":86},[11,1568,90],{},[11,1570,93],{},[11,1572,96],{},[98,1574,1576],{"className":1575,"code":102,"language":103,"meta":104},[101],[106,1577,102],{"__ignoreMap":104},[11,1579,110],{},[11,1581,113],{},[11,1583,116],{},[54,1585,1586,1588,1590,1592,1594,1596],{},[57,1587,121],{},[57,1589,124],{},[57,1591,127],{},[57,1593,130],{},[57,1595,133],{},[57,1597,136],{},[11,1599,139],{},[21,1601,143],{"id":142},[11,1603,146],{},[11,1605,149],{},[151,1607,1608,1610,1612,1614,1616,1618,1620,1622],{},[57,1609,155],{},[57,1611,158],{},[57,1613,161],{},[57,1615,164],{},[57,1617,167],{},[57,1619,170],{},[57,1621,173],{},[57,1623,176],{},[11,1625,179],{},[11,1627,182],{},[11,1629,185],{},[11,1631,188],{},[98,1633,1634],{"className":191,"code":192,"language":193,"meta":104,"style":104},[106,1635,1636,1644,1652,1660,1668,1676,1684,1692],{"__ignoreMap":104},[197,1637,1638,1640,1642],{"class":199,"line":200},[197,1639,204],{"class":203},[197,1641,208],{"class":207},[197,1643,212],{"class":211},[197,1645,1646,1648,1650],{"class":199,"line":215},[197,1647,218],{"class":203},[197,1649,208],{"class":207},[197,1651,223],{"class":211},[197,1653,1654,1656,1658],{"class":199,"line":226},[197,1655,229],{"class":203},[197,1657,208],{"class":207},[197,1659,234],{"class":211},[197,1661,1662,1664,1666],{"class":199,"line":237},[197,1663,240],{"class":203},[197,1665,208],{"class":207},[197,1667,245],{"class":211},[197,1669,1670,1672,1674],{"class":199,"line":248},[197,1671,251],{"class":203},[197,1673,208],{"class":207},[197,1675,256],{"class":211},[197,1677,1678,1680,1682],{"class":199,"line":259},[197,1679,262],{"class":203},[197,1681,208],{"class":207},[197,1683,267],{"class":211},[197,1685,1686,1688,1690],{"class":199,"line":270},[197,1687,273],{"class":203},[197,1689,208],{"class":207},[197,1691,278],{"class":211},[197,1693,1694,1696,1698],{"class":199,"line":281},[197,1695,284],{"class":203},[197,1697,208],{"class":207},[197,1699,289],{"class":211},[11,1701,292],{},[11,1703,295,1704,302],{},[32,1705,301],{"href":298,"rel":1706},[300],[11,1708,305],{},[21,1710,309],{"id":308},[11,1712,312],{},[314,1714,1715,1725],{},[317,1716,1717],{},[320,1718,1719,1721,1723],{},[323,1720,325],{},[323,1722,328],{},[323,1724,331],{},[333,1726,1727,1735,1743,1751,1759],{},[320,1728,1729,1731,1733],{},[338,1730,340],{},[338,1732,343],{},[338,1734,346],{},[320,1736,1737,1739,1741],{},[338,1738,351],{},[338,1740,354],{},[338,1742,357],{},[320,1744,1745,1747,1749],{},[338,1746,362],{},[338,1748,365],{},[338,1750,368],{},[320,1752,1753,1755,1757],{},[338,1754,373],{},[338,1756,376],{},[338,1758,379],{},[320,1760,1761,1763,1765],{},[338,1762,384],{},[338,1764,387],{},[338,1766,390],{},[11,1768,393],{},[314,1770,1771,1785],{},[317,1772,1773],{},[320,1774,1775,1777,1779,1781,1783],{},[323,1776,402],{},[323,1778,405],{},[323,1780,408],{},[323,1782,411],{},[323,1784,414],{},[333,1786,1787,1799,1811],{},[320,1788,1789,1791,1793,1795,1797],{},[338,1790,421],{},[338,1792,424],{},[338,1794,427],{},[338,1796,430],{},[338,1798,433],{},[320,1800,1801,1803,1805,1807,1809],{},[338,1802,438],{},[338,1804,441],{},[338,1806,444],{},[338,1808,447],{},[338,1810,450],{},[320,1812,1813,1815,1817,1819,1821],{},[338,1814,455],{},[338,1816,458],{},[338,1818,461],{},[338,1820,373],{},[338,1822,466],{},[11,1824,469,1825,474],{},[32,1826,473],{"href":472},[11,1828,477],{},[11,1830,480],{},[21,1832,484],{"id":483},[11,1834,487],{},[314,1836,1837,1847],{},[317,1838,1839],{},[320,1840,1841,1843,1845],{},[323,1842,496],{},[323,1844,499],{},[323,1846,502],{},[333,1848,1849,1857,1865,1873,1881,1889,1897],{},[320,1850,1851,1853,1855],{},[338,1852,509],{},[338,1854,512],{},[338,1856,515],{},[320,1858,1859,1861,1863],{},[338,1860,520],{},[338,1862,523],{},[338,1864,526],{},[320,1866,1867,1869,1871],{},[338,1868,430],{},[338,1870,533],{},[338,1872,536],{},[320,1874,1875,1877,1879],{},[338,1876,541],{},[338,1878,544],{},[338,1880,547],{},[320,1882,1883,1885,1887],{},[338,1884,552],{},[338,1886,555],{},[338,1888,558],{},[320,1890,1891,1893,1895],{},[338,1892,563],{},[338,1894,566],{},[338,1896,569],{},[320,1898,1899,1901,1903],{},[338,1900,574],{},[338,1902,577],{},[338,1904,580],{},[11,1906,583],{},[11,1908,586],{},[11,1910,589],{},[21,1912,593],{"id":592},[11,1914,596],{},[11,1916,599],{},[151,1918,1919,1921,1923,1925],{},[57,1920,604],{},[57,1922,607],{},[57,1924,610],{},[57,1926,613],{},[11,1928,616],{},[11,1930,619],{},[21,1932,623],{"id":622},[11,1934,626],{},[11,1936,629],{},[11,1938,632],{},[54,1940,1941,1943,1945,1947,1949,1951],{},[57,1942,637],{},[57,1944,640],{},[57,1946,643],{},[57,1948,646],{},[57,1950,649],{},[57,1952,652],{},[11,1954,655],{},[11,1956,658],{},[21,1958,662],{"id":661},[11,1960,665],{},[151,1962,1963,1967,1971,1975,1979,1983,1987,1991,1995,1999,2003,2010],{},[57,1964,1965,674],{},[671,1966,673],{},[57,1968,1969,680],{},[671,1970,679],{},[57,1972,1973,686],{},[671,1974,685],{},[57,1976,1977,692],{},[671,1978,691],{},[57,1980,1981,698],{},[671,1982,697],{},[57,1984,1985,704],{},[671,1986,703],{},[57,1988,1989,710],{},[671,1990,709],{},[57,1992,1993,716],{},[671,1994,715],{},[57,1996,1997,722],{},[671,1998,721],{},[57,2000,2001,728],{},[671,2002,727],{},[57,2004,2005,734,2007,740],{},[671,2006,733],{},[32,2008,739],{"href":737,"rel":2009},[300],[57,2011,2012,746],{},[671,2013,745],{},[21,2015,750],{"id":749},[11,2017,753],{},[11,2019,756],{},[151,2021,2022,2024,2026,2028,2030,2032,2034,2036],{},[57,2023,761],{},[57,2025,764],{},[57,2027,767],{},[57,2029,770],{},[57,2031,773],{},[57,2033,776],{},[57,2035,779],{},[57,2037,782],{},[11,2039,785],{},[787,2041,789],{},{"title":104,"searchDepth":215,"depth":215,"links":2043},[2044,2045,2046,2047,2048,2049,2050,2051,2052,2053],{"id":23,"depth":215,"text":24},{"id":48,"depth":215,"text":49},{"id":86,"depth":215,"text":87},{"id":142,"depth":215,"text":143},{"id":308,"depth":215,"text":309},{"id":483,"depth":215,"text":484},{"id":592,"depth":215,"text":593},{"id":622,"depth":215,"text":623},{"id":661,"depth":215,"text":662},{"id":749,"depth":215,"text":750},{},[812,813,814],[816,817,818],[820,821],{"title":5,"description":803},[826,827,828],{"id":2061,"title":2062,"author":6,"body":2063,"category":802,"description":2859,"extension":804,"featured":805,"heroImage":806,"meta":2860,"navigation":805,"path":2861,"publishedAt":809,"readingTime":2862,"relatedAgents":2863,"relatedArticles":2865,"relatedWorkflows":2866,"searchIntent":2867,"seo":2868,"stem":2869,"topics":2870,"updatedAt":809,"visual":829,"__hash__":2874},"articles\u002Farticles\u002Fwhat-ai-agent-handoff-should-include.md","What should an AI agent handoff include?",{"type":8,"value":2064,"toc":2846},[2065,2068,2071,2075,2078,2081,2104,2107,2110,2116,2120,2123,2201,2204,2208,2211,2220,2223,2229,2232,2236,2239,2242,2259,2262,2265,2269,2272,2285,2288,2291,2294,2298,2301,2304,2307,2310,2314,2317,2320,2340,2343,2346,2350,2353,2356,2359,2362,2368,2372,2375,2742,2745,2749,2752,2802,2805,2809,2812,2815,2838,2841,2844],[11,2066,2067],{},"An AI agent handoff should include the next objective, the accepted state and supporting evidence, only the context that changes the next decision, the agent’s authority and tools, the required output and acceptance criteria, recovery guidance, the next destination, and a stopping rule.",[11,2069,2070],{},"That is the minimum useful packet. A role prompt, a conversation transcript, or a message such as “review the draft” may be part of the handoff, but none of them makes the next step executable by itself.",[21,2072,2074],{"id":2073},"a-handoff-message-is-not-an-execution-packet","A handoff message is not an execution packet",[11,2076,2077],{},"Handoffs are often described as transfers between agents. One agent decides that another specialist should take over, calls a handoff tool, and passes some context.",[11,2079,2080],{},"That description covers the routing event. It does not answer the receiving agent’s operating questions:",[54,2082,2083,2086,2089,2092,2095,2098,2101],{},[57,2084,2085],{},"Which output is authoritative?",[57,2087,2088],{},"What has already been accepted?",[57,2090,2091],{},"Which evidence and policies apply?",[57,2093,2094],{},"What may this agent read or change?",[57,2096,2097],{},"What result must it return?",[57,2099,2100],{},"Who decides what happens after the result?",[57,2102,2103],{},"When should it stop?",[11,2105,2106],{},"A capable agent can investigate these questions. That is not always a failure. Research, diagnosis, and discovery may be the work. The avoidable friction is different: forcing the agent to rediscover workflow state the system already knows.",[11,2108,2109],{},"We encountered this distinction while testing our own workflow setup. Fresh agents could work around incomplete context by reading more files and reconstructing prior decisions. They still reached the goal. But broad role-level investigation added latency, while a targeted step packet let the agent move directly to the relevant action. The useful goal was not zero friction. It was to remove system-created guessing.",[11,2111,2112,2113,2115],{},"This is the narrow focus of a handoff packet. The broader ",[32,2114,1076],{"href":1075}," includes tool design, recovery, authority, and orchestration across the whole run. The packet is the local execution surface one agent receives now.",[21,2117,2119],{"id":2118},"include-eight-operating-fields","Include eight operating fields",[11,2121,2122],{},"The following structure is a practical synthesis from our workflow work, not a standard imposed by one agent framework. The fields can be assembled from durable state, defaults, and prior outputs; they do not need to become eight paragraphs in every prompt.",[314,2124,2125,2135],{},[317,2126,2127],{},[320,2128,2129,2132],{},[323,2130,2131],{},"Field",[323,2133,2134],{},"Question it answers",[333,2136,2137,2145,2153,2161,2169,2177,2185,2193],{},[320,2138,2139,2142],{},[338,2140,2141],{},"Objective and ownership",[338,2143,2144],{},"What must happen now, and who owns the next decision?",[320,2146,2147,2150],{},[338,2148,2149],{},"Accepted state and evidence",[338,2151,2152],{},"What is already true, and which refs prove it?",[320,2154,2155,2158],{},[338,2156,2157],{},"Bounded context and policies",[338,2159,2160],{},"Which prior decisions and rules affect this step?",[320,2162,2163,2166],{},[338,2164,2165],{},"Authority and tools",[338,2167,2168],{},"What may the agent inspect, change, or execute?",[320,2170,2171,2174],{},[338,2172,2173],{},"Output contract",[338,2175,2176],{},"What exact result, fields, or artifact must be returned?",[320,2178,2179,2182],{},[338,2180,2181],{},"Acceptance criteria",[338,2183,2184],{},"How can the agent tell that its responsibility is complete?",[320,2186,2187,2190],{},[338,2188,2189],{},"Recovery path",[338,2191,2192],{},"What should happen when an expected input, tool, or criterion fails?",[320,2194,2195,2198],{},[338,2196,2197],{},"Destination and stopping rule",[338,2199,2200],{},"Where does the result go, and when must the agent return control?",[11,2202,2203],{},"Each field removes a different ambiguity. Combining them into a long prose brief often hides those distinctions, so a structured packet is usually easier to inspect.",[21,2205,2207],{"id":2206},"name-the-objective-and-ownership","Name the objective and ownership",[11,2209,2210],{},"“Act as an editor” is a role. “Review the supplied article for unsupported material claims and return findings to the orchestrator” is an objective.",[11,2212,2213,2214,2219],{},"The packet should also state whether control transfers or returns. This varies across architectures. Microsoft’s ",[32,2215,2218],{"href":2216,"rel":2217},"https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fagent-framework\u002Fworkflows\u002Forchestrations\u002Fhandoff",[300],"handoff orchestration"," transfers task ownership to the receiving agent. In a manager or agent-as-tool pattern, the primary agent retains overall responsibility and receives a bounded specialist result.",[11,2221,2222],{},"The receiver should not need to infer which model applies. A useful packet might say:",[2224,2225,2226],"blockquote",{},[11,2227,2228],{},"You own the claim review only. Return findings to the orchestrator. Do not revise the article or expand its scope.",[11,2230,2231],{},"That sentence defines both responsibility and its boundary.",[21,2233,2235],{"id":2234},"pass-accepted-state-not-a-scavenger-hunt","Pass accepted state, not a scavenger hunt",[11,2237,2238],{},"A handoff should identify the current authoritative inputs directly. It should name the accepted brief, current draft, relevant predecessor output, and evidence refs. “Use the latest version in the project” moves state resolution back to the receiving agent.",[11,2240,2241],{},"Accepted state is more than a summary of what happened. It separates settled facts from open questions:",[54,2243,2244,2247,2250,2253,2256],{},[57,2245,2246],{},"the angle was accepted;",[57,2248,2249],{},"the draft at a specific ref is current;",[57,2251,2252],{},"two claims are intentionally marked unresolved;",[57,2254,2255],{},"the publication intent is packet only;",[57,2257,2258],{},"no image generation was selected.",[11,2260,2261],{},"This lets the agent preserve prior decisions instead of accidentally reopening them.",[11,2263,2264],{},"Evidence refs matter for the same reason. A reviewer should receive the claim map or source ledger it must evaluate, not a claim that “research was completed.” A downstream agent can then inspect the receipt when necessary without replaying the entire research phase.",[21,2266,2268],{"id":2267},"select-context-that-changes-the-next-decision","Select context that changes the next decision",[11,2270,2271],{},"Conversation history is useful, but it is not automatically the right handoff payload.",[11,2273,1072,2274,2279,2280,2284],{},[32,2275,2278],{"href":2276,"rel":2277},"https:\u002F\u002Fopenai.github.io\u002Fopenai-agents-python\u002Fhandoffs\u002F",[300],"OpenAI Agents SDK handoff guide"," separates small model-generated handoff metadata from application state and from the receiving agent’s main input. It also provides input filters that change which history items the next agent sees. Microsoft’s ",[32,2281,2283],{"href":737,"rel":2282},[300],"orchestration guidance"," recommends deciding whether the next agent needs full raw context, a compacted version, or only a new instruction set.",[11,2286,2287],{},"The practical rule is to include context when it changes a valid action or judgment. Keep the rest as durable references.",[11,2289,2290],{},"For an editorial review, the current voice guide and disclosure policy change the decision. A long transcript about earlier keyword research may not. For a debugging step, the failing test output and accepted requirement matter; unrelated implementation discussion does not.",[11,2292,2293],{},"Full history can still be correct when nuance across the whole conversation is the task. Bounded context is a selection rule, not a blanket instruction to summarize everything.",[21,2295,2297],{"id":2296},"resolve-tools-and-authority-together","Resolve tools and authority together",[11,2299,2300],{},"A tool name without an authority boundary leaves the agent guessing.",[11,2302,2303],{},"The packet should say which operations are available, what they are for, and which side effects are outside the step. If a reviewer can read files and run checks but cannot edit or publish, that boundary belongs beside the tools.",[11,2305,2306],{},"Resolved tools are better than broad discovery when the workflow already knows the target. “Run the website content sync in this directory” is more executable than “use the repository tools to verify the article.” A tool description should still expose important limits and likely failure modes, but the agent should not have to inspect an entire toolbox to locate the intended operation.",[11,2308,2309],{},"Authority should also end with the active responsibility. A review step does not inherit publication rights merely because publication exists later in the workflow.",[21,2311,2313],{"id":2312},"define-the-output-and-acceptance-contract","Define the output and acceptance contract",[11,2315,2316],{},"The receiving agent needs to know what a valid result looks like.",[11,2318,2319],{},"For a claim review, “provide feedback” is weak. A useful output contract could require:",[54,2321,2322,2325,2328,2331,2334,2337],{},[57,2323,2324],{},"finding;",[57,2326,2327],{},"affected claim or section;",[57,2329,2330],{},"evidence basis;",[57,2332,2333],{},"classification;",[57,2335,2336],{},"repair status;",[57,2338,2339],{},"unresolved question.",[11,2341,2342],{},"Acceptance criteria then define completion: all material claims were checked, unsupported claims were removed or marked unresolved, and findings were returned in the expected shape.",[11,2344,2345],{},"The distinction matters. An output schema can prove that required fields exist. Acceptance criteria evaluate whether the responsibility was actually fulfilled. A packet should carry both when the result feeds another agent.",[21,2347,2349],{"id":2348},"include-targeted-recovery-and-a-stopping-rule","Include targeted recovery and a stopping rule",[11,2351,2352],{},"“Retry if needed” is not recovery guidance.",[11,2354,2355],{},"Targeted recovery names the next safe action for failures the workflow can anticipate. If a predecessor handoff was truncated, the packet can provide the exact read needed to recover it. If a source is unavailable, it can tell the reviewer to return an unresolved finding instead of inventing support. If an external action lacks authority, it can require the agent to stop with a structured blocker.",[11,2357,2358],{},"The stopping rule is equally important. It prevents a specialist from turning one responsibility into a broader improvement project.",[11,2360,2361],{},"A reviewer should stop when its checks are complete and return findings. It should not implement every preference. A writer should stop when the accepted repair is made and the required evidence is attached. It should not redesign the workflow.",[11,2363,1072,2364,2367],{},[32,2365,2366],{"href":472},"orchestrator then triages feedback"," against the accepted plan.",[21,2369,2371],{"id":2370},"a-worked-handoff-packet","A worked handoff packet",[11,2373,2374],{},"The packet below is deliberately compact. Stable project rules and tool schemas can remain durable references; this payload resolves what the next agent needs for one article review.",[98,2376,2378],{"className":191,"code":2377,"language":193,"meta":104,"style":104},"step: editorial-review\n\nobjective:\n  task: Review the current article for unsupported material claims.\n  ownership: Return findings to the orchestrator; do not edit or publish.\n\naccepted_state:\n  draft_ref: website\u002Fcontent\u002Farticles\u002Fexample.md\n  angle_status: accepted\n  publication_intent: packet_only\n  evidence_refs:\n    - evidence-item:research-basis\n    - source-ledger:example\n\ncontext:\n  voice_guide_ref: artifact:current-voice-guide\n  disclosure_policy_ref: resource:public-disclosure\n\nauthority:\n  allowed:\n    - read the draft and named evidence\n    - inspect public primary sources\n  prohibited:\n    - modify the draft\n    - create publication jobs\n    - add work outside claim review\n\noutput:\n  required_fields:\n    - claim\n    - evidence_basis\n    - classification\n    - repair_needed\n  acceptance:\n    - every material claim was checked\n    - unsupported claims are identified\n    - preferences are separated from blockers\n\nrecovery:\n  missing_evidence: Return an unresolved finding with the missing ref.\n  truncated_handoff: Read the named predecessor result once.\n\ndestination: orchestrator\nstop_when: The claim report is complete or a blocking input is unavailable.\n",[106,2379,2380,2390,2395,2403,2413,2423,2427,2434,2444,2455,2466,2474,2483,2491,2496,2504,2515,2526,2531,2539,2547,2555,2563,2571,2579,2587,2595,2600,2608,2616,2624,2632,2640,2648,2656,2664,2672,2680,2685,2693,2704,2715,2720,2731],{"__ignoreMap":104},[197,2381,2382,2385,2387],{"class":199,"line":200},[197,2383,2384],{"class":203},"step",[197,2386,208],{"class":207},[197,2388,2389],{"class":211},"editorial-review\n",[197,2391,2392],{"class":199,"line":215},[197,2393,2394],{"emptyLinePlaceholder":805},"\n",[197,2396,2397,2400],{"class":199,"line":226},[197,2398,2399],{"class":203},"objective",[197,2401,2402],{"class":207},":\n",[197,2404,2405,2408,2410],{"class":199,"line":237},[197,2406,2407],{"class":203},"  task",[197,2409,208],{"class":207},[197,2411,2412],{"class":211},"Review the current article for unsupported material claims.\n",[197,2414,2415,2418,2420],{"class":199,"line":248},[197,2416,2417],{"class":203},"  ownership",[197,2419,208],{"class":207},[197,2421,2422],{"class":211},"Return findings to the orchestrator; do not edit or publish.\n",[197,2424,2425],{"class":199,"line":259},[197,2426,2394],{"emptyLinePlaceholder":805},[197,2428,2429,2432],{"class":199,"line":270},[197,2430,2431],{"class":203},"accepted_state",[197,2433,2402],{"class":207},[197,2435,2436,2439,2441],{"class":199,"line":281},[197,2437,2438],{"class":203},"  draft_ref",[197,2440,208],{"class":207},[197,2442,2443],{"class":211},"website\u002Fcontent\u002Farticles\u002Fexample.md\n",[197,2445,2447,2450,2452],{"class":199,"line":2446},9,[197,2448,2449],{"class":203},"  angle_status",[197,2451,208],{"class":207},[197,2453,2454],{"class":211},"accepted\n",[197,2456,2458,2461,2463],{"class":199,"line":2457},10,[197,2459,2460],{"class":203},"  publication_intent",[197,2462,208],{"class":207},[197,2464,2465],{"class":211},"packet_only\n",[197,2467,2469,2472],{"class":199,"line":2468},11,[197,2470,2471],{"class":203},"  evidence_refs",[197,2473,2402],{"class":207},[197,2475,2477,2480],{"class":199,"line":2476},12,[197,2478,2479],{"class":207},"    - ",[197,2481,2482],{"class":211},"evidence-item:research-basis\n",[197,2484,2486,2488],{"class":199,"line":2485},13,[197,2487,2479],{"class":207},[197,2489,2490],{"class":211},"source-ledger:example\n",[197,2492,2494],{"class":199,"line":2493},14,[197,2495,2394],{"emptyLinePlaceholder":805},[197,2497,2499,2502],{"class":199,"line":2498},15,[197,2500,2501],{"class":203},"context",[197,2503,2402],{"class":207},[197,2505,2507,2510,2512],{"class":199,"line":2506},16,[197,2508,2509],{"class":203},"  voice_guide_ref",[197,2511,208],{"class":207},[197,2513,2514],{"class":211},"artifact:current-voice-guide\n",[197,2516,2518,2521,2523],{"class":199,"line":2517},17,[197,2519,2520],{"class":203},"  disclosure_policy_ref",[197,2522,208],{"class":207},[197,2524,2525],{"class":211},"resource:public-disclosure\n",[197,2527,2529],{"class":199,"line":2528},18,[197,2530,2394],{"emptyLinePlaceholder":805},[197,2532,2534,2537],{"class":199,"line":2533},19,[197,2535,2536],{"class":203},"authority",[197,2538,2402],{"class":207},[197,2540,2542,2545],{"class":199,"line":2541},20,[197,2543,2544],{"class":203},"  allowed",[197,2546,2402],{"class":207},[197,2548,2550,2552],{"class":199,"line":2549},21,[197,2551,2479],{"class":207},[197,2553,2554],{"class":211},"read the draft and named evidence\n",[197,2556,2558,2560],{"class":199,"line":2557},22,[197,2559,2479],{"class":207},[197,2561,2562],{"class":211},"inspect public primary sources\n",[197,2564,2566,2569],{"class":199,"line":2565},23,[197,2567,2568],{"class":203},"  prohibited",[197,2570,2402],{"class":207},[197,2572,2574,2576],{"class":199,"line":2573},24,[197,2575,2479],{"class":207},[197,2577,2578],{"class":211},"modify the draft\n",[197,2580,2582,2584],{"class":199,"line":2581},25,[197,2583,2479],{"class":207},[197,2585,2586],{"class":211},"create publication jobs\n",[197,2588,2590,2592],{"class":199,"line":2589},26,[197,2591,2479],{"class":207},[197,2593,2594],{"class":211},"add work outside claim review\n",[197,2596,2598],{"class":199,"line":2597},27,[197,2599,2394],{"emptyLinePlaceholder":805},[197,2601,2603,2606],{"class":199,"line":2602},28,[197,2604,2605],{"class":203},"output",[197,2607,2402],{"class":207},[197,2609,2611,2614],{"class":199,"line":2610},29,[197,2612,2613],{"class":203},"  required_fields",[197,2615,2402],{"class":207},[197,2617,2619,2621],{"class":199,"line":2618},30,[197,2620,2479],{"class":207},[197,2622,2623],{"class":211},"claim\n",[197,2625,2627,2629],{"class":199,"line":2626},31,[197,2628,2479],{"class":207},[197,2630,2631],{"class":211},"evidence_basis\n",[197,2633,2635,2637],{"class":199,"line":2634},32,[197,2636,2479],{"class":207},[197,2638,2639],{"class":211},"classification\n",[197,2641,2643,2645],{"class":199,"line":2642},33,[197,2644,2479],{"class":207},[197,2646,2647],{"class":211},"repair_needed\n",[197,2649,2651,2654],{"class":199,"line":2650},34,[197,2652,2653],{"class":203},"  acceptance",[197,2655,2402],{"class":207},[197,2657,2659,2661],{"class":199,"line":2658},35,[197,2660,2479],{"class":207},[197,2662,2663],{"class":211},"every material claim was checked\n",[197,2665,2667,2669],{"class":199,"line":2666},36,[197,2668,2479],{"class":207},[197,2670,2671],{"class":211},"unsupported claims are identified\n",[197,2673,2675,2677],{"class":199,"line":2674},37,[197,2676,2479],{"class":207},[197,2678,2679],{"class":211},"preferences are separated from blockers\n",[197,2681,2683],{"class":199,"line":2682},38,[197,2684,2394],{"emptyLinePlaceholder":805},[197,2686,2688,2691],{"class":199,"line":2687},39,[197,2689,2690],{"class":203},"recovery",[197,2692,2402],{"class":207},[197,2694,2696,2699,2701],{"class":199,"line":2695},40,[197,2697,2698],{"class":203},"  missing_evidence",[197,2700,208],{"class":207},[197,2702,2703],{"class":211},"Return an unresolved finding with the missing ref.\n",[197,2705,2707,2710,2712],{"class":199,"line":2706},41,[197,2708,2709],{"class":203},"  truncated_handoff",[197,2711,208],{"class":207},[197,2713,2714],{"class":211},"Read the named predecessor result once.\n",[197,2716,2718],{"class":199,"line":2717},42,[197,2719,2394],{"emptyLinePlaceholder":805},[197,2721,2723,2726,2728],{"class":199,"line":2722},43,[197,2724,2725],{"class":203},"destination",[197,2727,208],{"class":207},[197,2729,2730],{"class":211},"orchestrator\n",[197,2732,2734,2737,2739],{"class":199,"line":2733},44,[197,2735,2736],{"class":203},"stop_when",[197,2738,208],{"class":207},[197,2740,2741],{"class":211},"The claim report is complete or a blocking input is unavailable.\n",[11,2743,2744],{},"The exact keys can change. The operating questions should not disappear.",[21,2746,2748],{"id":2747},"watch-for-common-handoff-failures","Watch for common handoff failures",[11,2750,2751],{},"Several packets look informative but still force reconstruction:",[54,2753,2754,2760,2766,2772,2778,2784,2790,2796],{},[57,2755,2756,2759],{},[671,2757,2758],{},"Summary only:"," explains what happened but does not identify authoritative state.",[57,2761,2762,2765],{},[671,2763,2764],{},"Role only:"," describes expertise but not the current objective or boundary.",[57,2767,2768,2771],{},[671,2769,2770],{},"History dump:"," passes everything and makes the receiver search for what matters.",[57,2773,2774,2777],{},[671,2775,2776],{},"Tool catalog:"," exposes operations without resolving which one applies or what authority is active.",[57,2779,2780,2783],{},[671,2781,2782],{},"Output without evidence:"," asks for a result but not the receipts its consumer needs.",[57,2785,2786,2789],{},[671,2787,2788],{},"Criteria without recovery:"," defines success but gives no valid response to missing inputs.",[57,2791,2792,2795],{},[671,2793,2794],{},"No destination:"," leaves the agent unsure whether to act, delegate, or return.",[57,2797,2798,2801],{},[671,2799,2800],{},"No stopping rule:"," lets a bounded task expand into open-ended improvement.",[11,2803,2804],{},"These are packet problems even when the model is capable enough to work around them.",[21,2806,2808],{"id":2807},"use-the-first-valid-action-test","Use the first-valid-action test",[11,2810,2811],{},"Give the packet to a fresh agent with a short instruction such as “continue this step.” Then observe what it must do before taking a valid action.",[11,2813,2814],{},"The packet is probably sufficient when the agent can answer:",[54,2816,2817,2820,2823,2826,2829,2832,2835],{},[57,2818,2819],{},"What am I responsible for?",[57,2821,2822],{},"Which input is authoritative?",[57,2824,2825],{},"Which decisions are already settled?",[57,2827,2828],{},"Which tools and side effects are allowed?",[57,2830,2831],{},"What must I return, and where?",[57,2833,2834],{},"What should I do if the expected path fails?",[57,2836,2837],{},"When must I stop?",[11,2839,2840],{},"Some investigation will remain. That is part of agent work. The warning sign is workflow archaeology: searching for the current draft, guessing which policy applies, discovering tool authority by failure, or reconstructing the terminal condition from conversation history.",[11,2842,2843],{},"A good handoff does not eliminate reasoning. It reserves reasoning for the task instead of spending it on avoidable ambiguity.",[787,2845,789],{},{"title":104,"searchDepth":215,"depth":215,"links":2847},[2848,2849,2850,2851,2852,2853,2854,2855,2856,2857,2858],{"id":2073,"depth":215,"text":2074},{"id":2118,"depth":215,"text":2119},{"id":2206,"depth":215,"text":2207},{"id":2234,"depth":215,"text":2235},{"id":2267,"depth":215,"text":2268},{"id":2296,"depth":215,"text":2297},{"id":2312,"depth":215,"text":2313},{"id":2348,"depth":215,"text":2349},{"id":2370,"depth":215,"text":2371},{"id":2747,"depth":215,"text":2748},{"id":2807,"depth":215,"text":2808},"A practical handoff packet for AI agents, covering objective, state, evidence, context, tools, output, recovery, ownership, and stopping rules.",{},"\u002Farticles\u002Fwhat-ai-agent-handoff-should-include","10 min read",[2864,1125,812],"stackos-sdlc-delivery",[817,816,818],[820,821],"Learn what an AI agent handoff packet should contain",{"title":2062,"description":2859},"articles\u002Fwhat-ai-agent-handoff-should-include",[2871,2872,2873],"AI agent handoffs","agent context","multi-agent workflows","ILOycz1b-xhns1eFyv6Re7qPlAczHxeOZDF8xBRV4wU",{"id":2876,"title":2877,"author":6,"body":2878,"category":802,"description":3126,"extension":804,"featured":805,"heroImage":806,"meta":3127,"navigation":805,"path":3128,"publishedAt":3129,"readingTime":3130,"relatedAgents":3131,"relatedArticles":3132,"relatedWorkflows":3134,"searchIntent":3135,"seo":3136,"stem":3137,"topics":3138,"updatedAt":3129,"visual":1516,"__hash__":3141},"articles\u002Farticles\u002Fai-agent-experience.md","Agent experience: the missing layer in AI agent orchestration",{"type":8,"value":2879,"toc":3118},[2880,2883,2886,2890,2893,2896,2904,2908,2911,2914,2917,2925,2928,2932,2935,2938,3000,3003,3006,3009,3012,3015,3019,3022,3025,3028,3031,3034,3038,3041,3044,3047,3050,3054,3057,3060,3063,3066,3069,3073,3076,3079,3102,3105,3112,3115],[11,2881,2882],{},"An orchestration plan can be logically correct and still fail at the moment an agent receives its next step. The workflow says “draft the article,” but the agent must discover the brief, infer the audience, locate the allowed tools, reconstruct prior decisions, decide what completion means, and determine where the result belongs.",[11,2884,2885],{},"That gap lives in the agent’s operating environment at the point of action.",[844,2887],{"caption":2888,"mode":1516,"title":2889},"Orchestration is experienced one claimed step at a time: context, authority, tools, outputs, recovery, and a stopping rule.","The workflow an agent actually receives",[11,2891,2892],{},"Agent experience is the per-step operating layer that makes an orchestration plan executable for a fresh agent. Operationally, it is the burden a system places on that agent to search, guess, rediscover, and recover before it can perform valid work.",[11,2894,2895],{},"This definition keeps the idea concrete. Search burden is time spent locating relevant state or instructions. Guessing burden appears when inputs, authority, or completion criteria are ambiguous. Rediscovery burden comes from reconstructing decisions the system already knows. Recovery burden is the work required to understand and repair a failed attempt.",[11,2897,2898,2899,2903],{},"These burdens are separate from the distinctions among an ",[32,2900,2902],{"href":2901},"\u002Flibrary\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator","AI agent, workflow, and orchestrator",". Those components may all be present while the claimed step remains difficult to execute.",[21,2905,2907],{"id":2906},"an-assignment-is-not-yet-an-executable-step","An assignment is not yet an executable step",[11,2909,2910],{},"“Review the implementation” is an assignment. It identifies an activity but leaves most operating questions unanswered.",[11,2912,2913],{},"Which implementation? Review against which requirements? May the reviewer run tests, inspect external systems, or modify files? What evidence should the review produce? Does “ready” mean no defects, no blocking defects, or acceptance of documented risk? If the review finds a problem, who receives it and in what form?",[11,2915,2916],{},"A capable agent can often fill these gaps. That is precisely the problem: successful execution now depends on inference that the orchestration system could have resolved before dispatch.",[11,2918,2919,2920,2924],{},"An executable step should let an agent move from claim to first valid action without rebuilding the workflow in its own context window. This is especially important in an ",[32,2921,2923],{"href":2922},"\u002Flibrary\u002Farticles\u002Fwhat-is-an-agentic-workflow","agentic workflow",", where later actions depend on runtime findings. Dynamic behavior increases the need for explicit local operating conditions; it does not remove it.",[11,2926,2927],{},"The claimed step is therefore the useful unit for examining agent experience.",[21,2929,2931],{"id":2930},"the-claimed-step-packet","The claimed-step packet",[11,2933,2934],{},"When an agent claims a step, it should receive a bounded packet containing what that step needs now. This prepared execution surface selects from project state instead of passing all of it through.",[11,2936,2937],{},"A useful packet includes:",[54,2939,2940,2946,2952,2958,2964,2970,2976,2982,2988,2994],{},[57,2941,2942,2945],{},[671,2943,2944],{},"Purpose:"," why the work exists and what downstream decision or action it supports.",[57,2947,2948,2951],{},[671,2949,2950],{},"Instructions and policies:"," the relevant rules, already selected for this step.",[57,2953,2954,2957],{},[671,2955,2956],{},"Completion criteria:"," observable conditions that distinguish finished work from plausible-looking progress.",[57,2959,2960,2963],{},[671,2961,2962],{},"Exact tools:"," callable operations, expected use, and important limitations.",[57,2965,2966,2969],{},[671,2967,2968],{},"Resolved inputs:"," concrete artifact references, resource identifiers, prior outputs, and configuration values rather than instructions to “find the latest.”",[57,2971,2972,2975],{},[671,2973,2974],{},"Bounded context:"," enough history to understand the work without replaying the whole run.",[57,2977,2978,2981],{},[671,2979,2980],{},"Output contracts:"," required fields, artifact formats, evidence, and status semantics.",[57,2983,2984,2987],{},[671,2985,2986],{},"Direct handoff:"," where the result goes and what the next actor needs from it.",[57,2989,2990,2993],{},[671,2991,2992],{},"Targeted recovery:"," likely failure modes and the next safe action for each one.",[57,2995,2996,2999],{},[671,2997,2998],{},"A stopping rule:"," when to return control instead of expanding the task.",[11,3001,3002],{},"These fields turn hidden orchestration knowledge into local operating knowledge.",[11,3004,3005],{},"The distinction between resolved inputs and broad context matters. A packet should say which approved brief to use, not provide a folder and ask the agent to identify the authoritative version. It should name the relevant test command, not merely mention that tests exist. It should link a predecessor’s accepted artifact, not force the agent to search conversation history for the last apparently complete draft.",[11,3007,3008],{},"Context is useful when it reduces uncertainty. Beyond that point, it becomes another search surface.",[11,3010,3011],{},"The same principle applies to recovery. “Retry if needed” transfers diagnosis back to the agent. A targeted recovery hint might instead say that a truncated handoff can be retrieved with one exact read, that an unavailable credential requires returning the step with a specific reason, or that a validation failure should go back to the producing step with the failed criterion attached.",[11,3013,3014],{},"A good recovery path narrows the next decision without pretending every failure can be anticipated.",[21,3016,3018],{"id":3017},"authority-should-match-the-active-step","Authority should match the active step",[11,3020,3021],{},"Instructions alone do not define what an agent can do. The executable step also needs an authority boundary.",[11,3023,3024],{},"A practical model grants tools and resources when the step becomes active, scoped to the operations and inputs required for that step. Completion, cancellation, or release of the step ends that authority. The agent does not need ambient access to every workflow capability, and it should not have to discover whether a documented operation is actually permitted.",[11,3026,3027],{},"The relationship should be legible: purpose leads to a permitted action, the action produces required evidence, and the evidence has a defined handoff.",[11,3029,3030],{},"If any link is missing, the agent must guess. If tools are described but unavailable, it enters recovery before substantive work begins. If broad tools are available without a step-level purpose, the system invites drift.",[11,3032,3033],{},"Approval can be part of this boundary when risk or organizational policy calls for it, but approval is not inherently required for every step. The important property is that authority is explicit, scoped, and legible to the acting agent.",[21,3035,3037],{"id":3036},"review-feedback-does-not-own-delivery","Review feedback does not own delivery",[11,3039,3040],{},"Independent review is often represented as a simple gate after production. In operation, the reviewer also needs a claimed-step packet: the artifact under review, the governing criteria, relevant evidence, permitted verification tools, and a structured way to report findings.",[11,3042,3043],{},"An independent reviewer still needs the relevant context. It evaluates the work against declared criteria rather than inheriting the producer’s conclusions as facts.",[11,3045,3046],{},"The orchestrator has a different responsibility: adjudicating what the findings are allowed to change. A supported blocker can stop progression. A specific repair can return to the producing step. A preference can remain advice. An unsupported or out-of-scope finding should not expand the delivery.",[11,3048,3049],{},"This is a feedback gate, but not a ritual approval step. It protects the agreed goal from review-driven drift while preserving independent scrutiny where it matters.",[21,3051,3053],{"id":3052},"a-bounded-observation-from-one-stackos-replay","A bounded observation from one StackOS replay",[11,3055,3056],{},"One recent StackOS cold-start replay provides a small implementation example. It should be read as first-party operating evidence, not as a productivity benchmark or universal proof.",[11,3058,3059],{},"During that replay, a draft specialist reported that it had used no tools and made no guesses while completing its assigned work. That report records the agent’s operating behavior alongside the artifact. We did not run a comparative test to isolate why it needed no additional discovery.",[11,3061,3062],{},"Another step received a truncated dependency handoff. Instead of searching broadly, the agent followed the packet’s targeted recovery hint and retrieved the one complete prior-step result it needed. Near the end of the run, the final stopping rule kept the active agent from starting another workflow, changing the workflow setup, or creating unrelated content after the requested outcome had been reached.",[11,3064,3065],{},"The run still contained ordinary latency and friction. Agents had to process context, produce outputs, and move through orchestration boundaries. One fresh subagent missed its bounded execution window. The observation establishes neither lower overhead nor gains across models or workflows.",[11,3067,3068],{},"Within that boundary, the replay records three useful behaviors: one specialist reported no guessing, targeted recovery constrained the response to a partial handoff, and an explicit stopping rule limited drift.",[21,3070,3072],{"id":3071},"the-vague-cold-start-test","The vague cold-start test",[11,3074,3075],{},"A direct way to inspect agent experience is to remove accumulated familiarity.",[11,3077,3078],{},"Give a fresh agent the kind of vague request a real operator might provide. Do not give it the workflow key, the design rationale, or a warm context window containing earlier exploration. Then observe whether the system helps it discover the right workflow and whether the claimed step answers these questions:",[151,3080,3081,3084,3087,3090,3093,3096,3099],{},[57,3082,3083],{},"What is the first valid action?",[57,3085,3086],{},"Which exact inputs should be used?",[57,3088,3089],{},"Which tools are permitted and available?",[57,3091,3092],{},"What observable criteria define completion?",[57,3094,3095],{},"What must be produced, and where does it go?",[57,3097,3098],{},"What should happen if the expected path fails?",[57,3100,3101],{},"When must the agent stop and return control?",[11,3103,3104],{},"The test exposes friction when the agent must search broadly for policy, infer which artifact is authoritative, guess whether it has permission, recreate prior decisions, or invent a recovery strategy. Those behaviors may still produce a successful result, but they reveal orchestration work leaking into the execution step.",[11,3106,3107,3108,3111],{},"Teams can apply the same test while following a practical guide to ",[32,3109,3110],{"href":34},"building an AI agent workflow",". For each step, record the agent’s first action, unresolved questions, searches, inferred assumptions, unavailable tools, recovery attempts, and work performed after the completion condition. The result is a friction map grounded in behavior rather than a subjective rating.",[11,3113,3114],{},"Some ambiguity belongs to the work, some discovery is intentional, and some failures require judgment. The design target is narrower: stop making each fresh agent reconstruct decisions that the system has already made.",[11,3116,3117],{},"Orchestration determines what should happen next. Agent experience determines whether the next agent can actually do it.",{"title":104,"searchDepth":215,"depth":215,"links":3119},[3120,3121,3122,3123,3124,3125],{"id":2906,"depth":215,"text":2907},{"id":2930,"depth":215,"text":2931},{"id":3017,"depth":215,"text":3018},{"id":3036,"depth":215,"text":3037},{"id":3052,"depth":215,"text":3053},{"id":3071,"depth":215,"text":3072},"AI agent orchestration is experienced one claimed step at a time. Here is how context, authority, tools, recovery, and stopping rules shape whether an agent can execute.",{},"\u002Farticles\u002Fai-agent-experience","2026-07-11","9 min read",[1125,812,813],[3133,1127,816],"ai-agent-vs-workflow-vs-orchestrator",[820,821],"Understand how to design the operating experience inside AI agent orchestration",{"title":2877,"description":3126},"articles\u002Fai-agent-experience",[3139,1076,3140],"AI agent orchestration","workflow design","uV1oEIIU0bekOi0eZ7egVtz64SWH2q_6b4myaRa7sf0",{"id":3143,"title":3144,"author":6,"body":3145,"category":802,"description":3427,"extension":804,"featured":805,"heroImage":806,"meta":3428,"navigation":805,"path":3429,"publishedAt":3129,"readingTime":3130,"relatedAgents":3430,"relatedArticles":3432,"relatedWorkflows":3433,"searchIntent":3434,"seo":3435,"stem":3436,"topics":3437,"updatedAt":3129,"visual":829,"__hash__":3438},"articles\u002Farticles\u002Fhow-to-build-ai-agent-workflow.md","How to build an AI agent workflow: start with the problem",{"type":8,"value":3146,"toc":3417},[3147,3150,3153,3157,3164,3168,3171,3174,3194,3197,3200,3206,3210,3213,3219,3225,3231,3237,3240,3244,3247,3250,3253,3258,3261,3264,3268,3271,3274,3277,3283,3287,3290,3293,3334,3337,3340,3343,3347,3350,3353,3356,3359,3362,3366,3369,3372,3375,3378,3382,3385,3414],[11,3148,3149],{},"Start a useful AI agent workflow with an operational problem: something that should move from an uncertain starting state to a useful, verifiable outcome. Models, prompt libraries, and agent diagrams come later.",[11,3151,3152],{},"That distinction changes the design. A chain of prompts describes what the model should say next. An operational contract describes what the system is allowed to do, what state it must preserve, how progress is evaluated, and when the job is finished.",[3154,3155],"article-workflow-visual",{"title":3156,"workflow":820},"Design backward from a useful outcome",[11,3158,3159,3160,3163],{},"This is also what separates a workflow from adjacent concepts. An ",[32,3161,3162],{"href":2901},"agent, workflow, and orchestrator"," can all involve model reasoning, but they carry different responsibilities. The workflow defines the operating boundary. The orchestrator decides how to advance within it. Agents perform bounded work.",[21,3165,3167],{"id":3166},"why-prompt-chains-become-fragile","Why prompt chains become fragile",[11,3169,3170],{},"Prompt chains often look convincing in a prototype. One prompt gathers information, another drafts, and a third reviews. Each stage passes text to the next.",[11,3172,3173],{},"The fragility appears when the input is incomplete, a tool fails, a reviewer finds a real defect, or the work resumes after interruption. The chain has no reliable answer to questions such as:",[54,3175,3176,3179,3182,3185,3188,3191],{},[57,3177,3178],{},"Which facts were verified, and where did they come from?",[57,3180,3181],{},"Is a review comment a blocker, a repair, or an unsupported preference?",[57,3183,3184],{},"Can a failed step be retried without repeating side effects?",[57,3186,3187],{},"What remains unfinished?",[57,3189,3190],{},"Has the requested outcome already been reached?",[57,3192,3193],{},"Which instructions still apply after several rounds of generated text?",[11,3195,3196],{},"Prompting alone does not create durable state or explicit control flow for these questions. A larger context window can hide that gap without closing it.",[11,3198,3199],{},"A prompt chain also tends to mix reasoning, state, and control flow. The model is expected to remember prior decisions, infer the current phase, choose tools, preserve constraints, and decide whether to stop. Small ambiguities accumulate. Later steps inherit summaries of summaries rather than a stable account of the job.",[11,3201,3202,3203,3205],{},"Representing those responsibilities explicitly makes an ",[32,3204,2923],{"href":2922}," easier to inspect when something changes.",[21,3207,3209],{"id":3208},"define-the-job-before-defining-the-agents","Define the job before defining the agents",[11,3211,3212],{},"Start with four descriptions: the problem, the useful outcome, the operator path, and the agent path.",[11,3214,1072,3215,3218],{},[671,3216,3217],{},"problem"," describes the operational gap. “We need a five-agent research system” is an implementation preference. “An editor cannot tell which claims in a draft are supported by the supplied sources” is a problem.",[11,3220,1072,3221,3224],{},[671,3222,3223],{},"useful outcome"," is the state in which that problem has been resolved. It should be inspectable. For the example above, the outcome might be a publishable draft whose material claims are linked to evidence, with unresolved claims clearly identified.",[11,3226,1072,3227,3230],{},[671,3228,3229],{},"operator path"," describes what a person initiating or supervising the workflow must do. What do they provide? Which choices can only they make? What can they inspect or revise? If the operator must repeatedly reconstruct hidden workflow state from chat history, the contract is incomplete.",[11,3232,1072,3233,3236],{},[671,3234,3235],{},"agent path"," describes how the system turns the initial inputs into the outcome. It names the required stages, dependencies, tools, state transitions, and recovery behavior. It should not assume that the agent will infer the intended route from a vague goal.",[11,3238,3239],{},"The two paths should meet at explicit interaction points, but they do not need a mandatory approval after every step. Some workflows can proceed automatically within a narrow boundary. Others need a decision when evidence conflicts, scope changes, or an external side effect is about to occur. The contract should reflect the actual risk rather than adding ceremonial checkpoints.",[21,3241,3243],{"id":3242},"work-backward-from-a-terminal-condition","Work backward from a terminal condition",[11,3245,3246],{},"A workflow needs a definition of done that can survive imperfect execution.",[11,3248,3249],{},"“Produce a good article” is not a terminal condition. Neither is “continue until the reviewer is satisfied.” Both delegate completion to an unbounded judgment.",[11,3251,3252],{},"A stronger terminal condition combines observable state with acceptance criteria. For example:",[2224,3254,3255],{},[11,3256,3257],{},"The draft exists, required sections are present, material claims have supporting evidence or an explicit unresolved status, blocking review findings are repaired, and the output passes the sanitization checks.",[11,3259,3260],{},"This gives the orchestrator something concrete to evaluate. It also prevents the workflow from looping because a reviewer can always imagine another improvement.",[11,3262,3263],{},"Terminal conditions should distinguish failure from incompleteness. Missing credentials, unavailable evidence, and contradictory operator requirements may prevent completion. Those states should produce structured recovery information: what failed, what was preserved, and what action could unblock the run.",[21,3265,3267],{"id":3266},"keep-durable-state-outside-the-conversation","Keep durable state outside the conversation",[11,3269,3270],{},"Conversation context is useful working memory. It is a poor system of record.",[11,3272,3273],{},"Durable workflow state should capture the facts needed to resume or audit the job: inputs, source references, decisions, step status, outputs, findings, retries, and unresolved issues. Generated prose can be part of that state, but it should not be the only place where the workflow records what happened.",[11,3275,3276],{},"While building StackOS, we have treated this separation as an authoring constraint. The workflow contracts we are refining represent run state, step boundaries, grants, findings, and outputs independently from an agent’s conversational context. That is implementation experience, not proof that every workflow needs the same storage model. The useful principle is narrower: state required for correct continuation should not depend on a model reconstructing it from dialogue.",[11,3278,3279,3280,3282],{},"Durable state changes the ",[32,3281,1076],{"href":1075},". An agent entering halfway through a run can inspect the current state instead of performing archaeology on a transcript.",[21,3284,3286],{"id":3285},"make-every-step-an-explicit-packet","Make every step an explicit packet",[11,3288,3289],{},"A step should arrive as a bounded packet of work. A role name followed by the entire project history leaves the agent to reconstruct the real assignment.",[11,3291,3292],{},"A useful step packet contains:",[54,3294,3295,3300,3306,3311,3316,3322,3328],{},[57,3296,3297,3299],{},[671,3298,2944],{}," why the step exists and what downstream decision it supports.",[57,3301,3302,3305],{},[671,3303,3304],{},"Inputs:"," the artifacts, references, and state the step may rely on.",[57,3307,3308,3310],{},[671,3309,2974],{}," the relevant constraints without unrelated run history.",[57,3312,3313,3315],{},[671,3314,2962],{}," the operations available for this step, including their scope.",[57,3317,3318,3321],{},[671,3319,3320],{},"Expected outputs:"," the artifact or state change the step must produce.",[57,3323,3324,3327],{},[671,3325,3326],{},"Criteria:"," the checks that determine whether the output is acceptable.",[57,3329,3330,3333],{},[671,3331,3332],{},"Recovery:"," how to report missing inputs, tool failures, ambiguity, or partial work.",[11,3335,3336],{},"Consider a claim-review step. Its purpose is not to “improve the draft.” It is to identify material claims, compare them with allowed evidence, and emit structured findings. Its tools might permit reading sources and recording findings but not rewriting the article. Its output distinguishes supported claims, unsupported claims, and cases where the available evidence is inconclusive.",[11,3338,3339],{},"That packet gives the reviewer enough freedom to reason without giving it ownership of the whole delivery. It also makes failures local. If evidence is missing, the workflow can repair that dependency rather than restart content production.",[11,3341,3342],{},"Exact tools matter because capability is part of the contract. An instruction such as “do not publish” is weaker than a step that has no publishing operation available. Tool boundaries turn behavioral expectations into operating constraints.",[21,3344,3346],{"id":3345},"give-one-orchestrator-ownership-of-progression","Give one orchestrator ownership of progression",[11,3348,3349],{},"A practical default is one reasoning orchestrator that owns progression: inspecting state, selecting the next eligible step, evaluating outputs, and checking the terminal condition. Add a specialist when the task needs a distinct context, tool boundary, or evaluation discipline—not simply because the brief contains several kinds of work.",[11,3351,3352],{},"In a content-production workflow we have been authoring for StackOS, one orchestrator coordinates bounded evidence, writing, claim, voice, and sanitization specialists. Each specialist has a different job and output contract. None independently decides that the entire article is complete.",[11,3354,3355],{},"The orchestrator also acts as the feedback gatekeeper. Review findings are classified before they affect delivery. A supported blocker can reopen an earlier step. A specific, valid repair can become bounded follow-up work. An unsupported preference or a finding outside the agreed scope does not silently expand the job.",[11,3357,3358],{},"This classification is designed to prevent a familiar multi-agent failure mode: every reviewer becomes a new source of authority. Without classification, one agent’s stylistic suggestion can override the original brief, trigger unnecessary rewrites, and create another review cycle. Feedback should change delivery only when the workflow contract says that kind of finding matters.",[11,3360,3361],{},"This is not a universal claim that every system needs exactly one orchestrator. It is a practical default for workflows where several bounded tasks contribute to one outcome. Additional reasoning authorities should have a clear ownership boundary, not merely a different persona.",[21,3363,3365],{"id":3364},"verify-the-cold-start","Verify the cold start",[11,3367,3368],{},"A workflow that succeeds only when its designer supplies unstated context is not finished.",[11,3370,3371],{},"Cold-start verification gives a fresh agent the kind of vague request an actual operator might provide and observes what happens. Does the agent locate the workflow? Does it inspect state and requirements? Does it ask for a genuinely missing choice? Or does it guess the project, invent inputs, and begin producing output?",[11,3373,3374],{},"While refining our StackOS workflow guidance, we use fresh-agent scenarios to expose these gaps. We are testing whether the operating contract leads an unfamiliar agent toward the intended path, not whether the model can improvise a plausible response.",[11,3376,3377],{},"A good cold start should make the safe next action easier than guessing.",[21,3379,3381],{"id":3380},"a-compact-workflow-design-test","A compact workflow design test",[11,3383,3384],{},"Before adding another prompt or specialist, test the workflow with a short sequence of questions:",[151,3386,3387,3390,3393,3396,3399,3402,3405,3408,3411],{},[57,3388,3389],{},"What operational problem is being resolved?",[57,3391,3392],{},"What observable state counts as a useful outcome?",[57,3394,3395],{},"What does the operator provide, decide, and receive?",[57,3397,3398],{},"What path may the agent take, and which actions are outside its boundary?",[57,3400,3401],{},"Where does durable state live?",[57,3403,3404],{},"Does each step have explicit inputs, tools, outputs, criteria, and recovery?",[57,3406,3407],{},"Who evaluates findings and decides whether they change the run?",[57,3409,3410],{},"Can a fresh agent find the path without private context?",[57,3412,3413],{},"Can the workflow stop deterministically?",[11,3415,3416],{},"If the answers are vague, a more elaborate agent topology can make the ambiguity harder to see. Start with the problem, define the contract, and let the agents occupy only the boundaries the work actually requires.",{"title":104,"searchDepth":215,"depth":215,"links":3418},[3419,3420,3421,3422,3423,3424,3425,3426],{"id":3166,"depth":215,"text":3167},{"id":3208,"depth":215,"text":3209},{"id":3242,"depth":215,"text":3243},{"id":3266,"depth":215,"text":3267},{"id":3285,"depth":215,"text":3286},{"id":3345,"depth":215,"text":3346},{"id":3364,"depth":215,"text":3365},{"id":3380,"depth":215,"text":3381},"A practical way to design AI agent workflows from the outcome backward, with explicit state, step contracts, feedback boundaries, and cold-start verification.",{},"\u002Farticles\u002Fhow-to-build-ai-agent-workflow",[3431,1124,812],"stackos-workflow-workflow-author",[3133,1127,817],[820,821],"Learn how to build an AI agent workflow from the problem and outcome backward",{"title":3144,"description":3427},"articles\u002Fhow-to-build-ai-agent-workflow",[826,1135,1134],"I59u29X8EdoopdGoZws9pKiDaHQtKY8L6q2TQAeeyeU",{"id":3440,"title":3441,"author":6,"body":3442,"category":802,"description":3657,"extension":804,"featured":805,"heroImage":806,"meta":3658,"navigation":805,"path":3659,"publishedAt":3660,"readingTime":1122,"relatedAgents":3661,"relatedArticles":3662,"relatedWorkflows":3664,"searchIntent":3665,"seo":3666,"stem":3667,"topics":3668,"updatedAt":809,"visual":1516,"__hash__":3672},"articles\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator.md","AI agent vs. workflow vs. orchestrator: what is the difference?",{"type":8,"value":3443,"toc":3648},[3444,3447,3450,3454,3502,3506,3509,3512,3523,3526,3529,3533,3536,3539,3542,3545,3549,3552,3555,3558,3562,3565,3582,3585,3589,3592,3595,3598,3601,3605,3608,3611,3615,3618,3635,3638],[11,3445,3446],{},"An AI agent owns a bounded responsibility. A workflow defines the durable execution contract. An orchestrator reasons about the whole job: what should happen next, which agent or tool should act, and which feedback belongs in the accepted plan.",[11,3448,3449],{},"The distinction is less about names than ownership. When ownership blurs, agents reconstruct state, workflows become long prompts, and orchestrators accept every plausible suggestion.",[844,3451],{"caption":3452,"mode":1516,"title":3453},"The workflow holds the contract. Agents handle bounded responsibilities. The orchestrator decides how the complete job should move.","One job, three different owners",[314,3455,3456,3469],{},[317,3457,3458],{},[320,3459,3460,3463,3466],{},[323,3461,3462],{},"Component",[323,3464,3465],{},"What it owns",[323,3467,3468],{},"What it should not own",[333,3470,3471,3481,3492],{},[320,3472,3473,3475,3478],{},[338,3474,994],{},[338,3476,3477],{},"One bounded judgment, transformation, review, or execution responsibility",[338,3479,3480],{},"Quietly redefining the accepted plan",[320,3482,3483,3486,3489],{},[338,3484,3485],{},"Workflow",[338,3487,3488],{},"State, dependencies, tool boundaries, expected outputs, acceptance criteria, and recovery paths",[338,3490,3491],{},"Deciding every exception at runtime",[320,3493,3494,3496,3499],{},[338,3495,1026],{},[338,3497,3498],{},"Next-step reasoning, context assembly, delegation, feedback triage, and recovery",[338,3500,3501],{},"Performing every specialist task or accepting every reviewer idea",[21,3503,3505],{"id":3504},"what-is-an-ai-agent","What is an AI agent?",[11,3507,3508],{},"An AI agent is a model operating under a role contract for the current work. That contract should name its responsibility, relevant context, tools and authority, required output, acceptance criteria, and recovery path.",[11,3510,3511],{},"The work can call for different kinds of agents:",[54,3513,3514,3517,3520],{},[57,3515,3516],{},"A reasoning agent makes a bounded judgment and explains why.",[57,3518,3519],{},"A mechanical agent performs a defined transformation or handoff without taking over strategy.",[57,3521,3522],{},"A review agent challenges another result and returns findings for adjudication.",[11,3524,3525],{},"These roles can use the same underlying model. The important separation is responsibility, not model count.",[11,3527,3528],{},"A good agent experience matters here. The agent should receive the state that changes its next decision, the intended tool path, and a clear stopping rule. It can still investigate when investigation is part of the task. It should not have to rediscover workflow state the system already knows.",[21,3530,3532],{"id":3531},"what-is-a-workflow","What is a workflow?",[11,3534,3535],{},"A workflow is the repeatable shape and durable state of the work. It defines the inputs, stages, dependencies, allowed tools and actions, expected outputs, acceptance criteria, and known recovery paths.",[11,3537,3538],{},"Start the workflow with the problem AI should help solve and the terminal condition for useful completion. Only then decide which steps or roles are necessary.",[11,3540,3541],{},"The workflow should remove avoidable guessing without scripting every conversation. “Claim review must return supported, unresolved, and cut claims with evidence refs” is a useful contract. Prescribing every sentence the reviewer should write is usually not.",[11,3543,3544],{},"This is why a workflow is more useful than a long prompt. A prompt supplies instructions for one turn. A workflow keeps the accepted state, relationships, authority, results, and receipts available across the job.",[21,3546,3548],{"id":3547},"what-is-an-orchestrator","What is an orchestrator?",[11,3550,3551],{},"An orchestrator is the reasoning role responsible for the complete job. It reads the workflow state, chooses the next valid step, assembles context, delegates bounded work, handles exceptions, and keeps delivery aligned with the accepted plan.",[11,3553,3554],{},"It is also the gatekeeper for feedback. A reviewer finding is a claim, not an instruction. The orchestrator checks it against the goal, evidence, root cause, and user impact. It accepts blockers and useful repairs, records preferences when they matter, and rejects suggestions that would expand or redirect the work.",[11,3556,3557],{},"Human input is not a routine orchestrator stage. It is needed when intent, authority, disclosure, or a consequential choice is materially missing. Otherwise the orchestrator should make the bounded decision and keep the job moving.",[21,3559,3561],{"id":3560},"how-do-they-work-together","How do they work together?",[11,3563,3564],{},"Take an article production job:",[151,3566,3567,3570,3573,3576,3579],{},[57,3568,3569],{},"The workflow stores the sequence from research through drafting and review. It also defines the output expected from each step and the criteria for completion.",[57,3571,3572],{},"The orchestrator reads the request and current state. It may skip an interview because the operator’s experience is already captured, or ask a bounded question because a material claim has no source.",[57,3574,3575],{},"Specialist agents collect evidence, draft the article, review claims, and check disclosure within their assigned boundaries.",[57,3577,3578],{},"Review findings return to the orchestrator. It decides which findings require repair and which are preferences or scope drift.",[57,3580,3581],{},"The job stops when the accepted output exists, material claims are supported or explicitly unresolved, blocking findings are repaired, and the requested verification passes.",[11,3583,3584],{},"In the StackOS model, the agent makes these decisions. StackOS stores the workflow and run state, scopes tool calls, and records what happened. The product is evidence for the separation, not a substitute for the reasoning role.",[21,3586,3588],{"id":3587},"what-did-we-learn-from-refining-real-workflows","What did we learn from refining real workflows?",[11,3590,3591],{},"Two failures made the distinction concrete for us.",[11,3593,3594],{},"First, fresh agents could complete a workflow with incomplete handoffs, but they spent time locating the current state, relevant tools, and expected result. The fix was not another specialist. The workflow and handoff needed to carry the context the system already knew.",[11,3596,3597],{},"Second, reviewers could always imagine another improvement. When the orchestrator treated every suggestion as delivery work, the plan drifted and the job kept expanding. The fix was a stronger gatekeeper: compare feedback with the accepted plan, implement supported repairs, and leave unrelated improvements out.",[11,3599,3600],{},"Both failures involved capable agents. The missing pieces were workflow state and orchestrator judgment.",[21,3602,3604],{"id":3603},"do-you-need-multiple-models","Do you need multiple models?",[11,3606,3607],{},"No. One model can take several roles at different stages, or a team can choose different models for cost, latency, tool use, or domain strength.",[11,3609,3610],{},"The more important separation is responsibility. A research role should preserve sources. A review role should challenge the draft independently. The orchestrator should adjudicate the result without quietly taking over either role.",[21,3612,3614],{"id":3613},"which-part-should-you-design-first","Which part should you design first?",[11,3616,3617],{},"Use this order:",[151,3619,3620,3623,3626,3629,3632],{},[57,3621,3622],{},"Define the problem, useful outcome, side-effect boundary, and terminal condition.",[57,3624,3625],{},"Build the workflow around the state, dependencies, authority, evidence, and recovery the job needs.",[57,3627,3628],{},"Define what the orchestrator must reason about: next steps, exceptions, feedback, drift, and closeout.",[57,3630,3631],{},"Add an agent only when a bounded responsibility deserves its own context and output contract.",[57,3633,3634],{},"Give the workflow to a fresh agent, observe the work, and ask where it had to guess, investigate, or make an undocumented decision.",[11,3636,3637],{},"This keeps the system grounded in the work. You are not collecting agents because they sound impressive. You are deciding where state lives, who reasons about the whole job, and who owns each necessary piece.",[11,3639,3640,3641,3644,3645,3647],{},"For the adjacent concepts, see ",[32,3642,3643],{"href":2922},"what makes a workflow agentic"," and the practical guide to ",[32,3646,1076],{"href":1075},".",{"title":104,"searchDepth":215,"depth":215,"links":3649},[3650,3651,3652,3653,3654,3655,3656],{"id":3504,"depth":215,"text":3505},{"id":3531,"depth":215,"text":3532},{"id":3547,"depth":215,"text":3548},{"id":3560,"depth":215,"text":3561},{"id":3587,"depth":215,"text":3588},{"id":3603,"depth":215,"text":3604},{"id":3613,"depth":215,"text":3614},"A workflow stores the execution contract. Agents own bounded responsibilities. The orchestrator reasons about the whole job and gates feedback, exceptions, and drift.",{},"\u002Farticles\u002Fai-agent-vs-workflow-vs-orchestrator","2026-07-09",[1125,812],[1127,3663],"use-codex-claude-gemini-with-existing-tools",[820,821],"Compare AI agents, workflows, and orchestrators in plain language",{"title":3441,"description":3657},"articles\u002Fai-agent-vs-workflow-vs-orchestrator",[3669,3670,3671],"AI agents","orchestrators","agentic workflows","5dbHMEnUQm_EksylaO0-_-Uc38_NGPKp4CHwoHL24hA",{"id":3674,"title":3675,"author":6,"body":3676,"category":3840,"description":3841,"extension":804,"featured":3842,"heroImage":806,"meta":3843,"navigation":805,"path":3844,"publishedAt":3660,"readingTime":3845,"relatedAgents":3846,"relatedArticles":3848,"relatedWorkflows":3849,"searchIntent":3850,"seo":3851,"stem":3852,"topics":3853,"updatedAt":809,"visual":3690,"__hash__":3857},"articles\u002Farticles\u002Fhow-ai-agents-use-accounts-safely.md","How can AI agents use business accounts without seeing the login?",{"type":8,"value":3677,"toc":3833},[3678,3681,3684,3687,3692,3696,3699,3713,3716,3720,3723,3726,3730,3733,3736,3753,3756,3759,3763,3766,3774,3789,3792,3796,3799,3822,3825],[11,3679,3680],{},"An AI agent does not need a password or API key to use a business account. It needs three things: a safe reference to the account, authority to request a named action, and the result of that action.",[11,3682,3683],{},"The credential can stay inside a trusted action layer. The agent chooses what to request. The action layer validates the request, uses the credential, and returns a sanitized result.",[11,3685,3686],{},"This is the boundary we use in StackOS. It lets the agent work without turning its prompt, workflow state, or logs into a credential store.",[844,3688],{"caption":3689,"mode":3690,"title":3691},"StackOS keeps the credential inside its local daemon, checks the requested action, and returns a sanitized result.","security","The agent requests. The action layer executes.",[21,3693,3695],{"id":3694},"what-should-the-model-receive","What should the model receive?",[11,3697,3698],{},"The model needs enough information to choose the right connection and action:",[54,3700,3701,3704,3707,3710],{},[57,3702,3703],{},"A provider and account profile name, or another safe reference",[57,3705,3706],{},"Whether the connection is ready",[57,3708,3709],{},"The capabilities and scopes available to it",[57,3711,3712],{},"The contract for the action it wants to request",[11,3714,3715],{},"It does not need the raw token, password, private key, or OAuth refresh token. In StackOS, an opaque credential reference identifies the connection without functioning as the credential itself.",[21,3717,3719],{"id":3718},"where-does-the-secret-stay","Where does the secret stay?",[11,3721,3722],{},"StackOS runs locally on the user’s Mac. The operator enters credentials through the local admin surface, and the daemon owns their storage. When an action runs, StackOS decrypts the credential inside the provider connector. The plaintext value is not serialized into the agent-facing request or response.",[11,3724,3725],{},"That gives us a practical rule: credentials do not belong in prompts, workflow files, project resources, content artifacts, or repository configuration. All of those can be copied, logged, or shared long after the action finishes.",[21,3727,3729],{"id":3728},"what-prevents-an-agent-from-doing-anything-it-wants","What prevents an agent from doing anything it wants?",[11,3731,3732],{},"The useful question is not whether the account is connected. It is whether this agent, in this step, can request this action through this account.",[11,3734,3735],{},"In StackOS, a call passes through a concrete sequence:",[151,3737,3738,3741,3744,3747,3750],{},[57,3739,3740],{},"StackOS resolves one provider profile instead of handing the agent a collection of credentials.",[57,3742,3743],{},"The agent names a registered action and supplies a payload that must pass that action’s contract.",[57,3745,3746],{},"Inside a workflow, the current step must have an explicit tool grant and a matching action reference. A research step cannot become a publishing step simply because both use the same connected account.",[57,3748,3749],{},"The daemon resolves the credential and calls the provider. Only the connector sees the plaintext secret.",[57,3751,3752],{},"Writes use idempotency protection, and the result is stored as a redacted action receipt with status, timing, and error context.",[11,3754,3755],{},"For a one-off write outside a workflow, the caller must explicitly confirm the named action and state its intent. That is an execution check, not a rule that a human must approve every agent step.",[11,3757,3758],{},"Human approval can still be added when a genuinely consequential action or missing authority calls for it. It is not the main security boundary. A broad token behind an approval click is still a broad token.",[21,3760,3762],{"id":3761},"is-local-software-enough-by-itself","Is local software enough by itself?",[11,3764,3765],{},"No. Running locally reduces how far secrets travel, but location is only one part of the design. Safe account access also needs narrow permissions, typed actions, grant enforcement, input validation, idempotency, redaction, revocation, and an audit trail.",[11,3767,3768,3769,3647],{},"The general principle is least privilege: give the agent only the resources and authority it needs for the current work. That is the same boundary described by ",[32,3770,3773],{"href":3771,"rel":3772},"https:\u002F\u002Fcsrc.nist.gov\u002Fglossary\u002Fterm\u002Fleast_privilege",[300],"NIST’s definition of least privilege",[11,3775,3776,3777,3782,3783,3788],{},"If the action layer is remote, the same boundary has to survive the network. The current ",[32,3778,3781],{"href":3779,"rel":3780},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fspecification\u002F2025-11-25\u002Fbasic\u002Fauthorization",[300],"MCP authorization specification"," uses resource-bound authorization and scope minimization, while the official ",[32,3784,3787],{"href":3785,"rel":3786},"https:\u002F\u002Fmodelcontextprotocol.io\u002Fdocs\u002Ftutorials\u002Fsecurity\u002Fsecurity_best_practices",[300],"MCP security guidance"," forbids token passthrough. A server should not accept a broad token intended for something else and simply forward it downstream.",[11,3790,3791],{},"An agent can still make a bad decision. These controls limit what it can reach, leave a receipt, and give the operator a place to revoke access or recover.",[21,3793,3795],{"id":3794},"what-should-teams-ask-before-connecting-an-account","What should teams ask before connecting an account?",[11,3797,3798],{},"Ask these questions:",[151,3800,3801,3804,3807,3810,3813,3816,3819],{},[57,3802,3803],{},"Where is the credential entered, stored, and decrypted?",[57,3805,3806],{},"Can the model, a tool response, or a log ever receive the raw value?",[57,3808,3809],{},"Which exact account, scopes, and actions does the connection allow?",[57,3811,3812],{},"Which workflow steps can request each action?",[57,3814,3815],{},"What prevents a retry from creating a duplicate external change?",[57,3817,3818],{},"What receipt is recorded, and which fields are redacted?",[57,3820,3821],{},"How is access tested, rotated, and revoked?",[11,3823,3824],{},"If those answers are vague, the connection is too broad.",[11,3826,3827,3828,3832],{},"We built StackOS around this boundary because hiding a password in the interface is not enough. The important line is where the credential becomes usable, who can ask for which action, and what trace remains afterward. The ",[32,3829,3831],{"href":3830},"\u002Flibrary\u002Fworkflows","workflow library"," shows how those account actions fit into visible work rather than appearing as isolated tool calls.",{"title":104,"searchDepth":215,"depth":215,"links":3834},[3835,3836,3837,3838,3839],{"id":3694,"depth":215,"text":3695},{"id":3718,"depth":215,"text":3719},{"id":3728,"depth":215,"text":3729},{"id":3761,"depth":215,"text":3762},{"id":3794,"depth":215,"text":3795},"Security","The model does not need the password. It needs a safe account reference, a bounded action, and a trusted execution layer that keeps credentials outside its context.",false,{},"\u002Farticles\u002Fhow-ai-agents-use-accounts-safely","6 min read",[3847],"branding-sanitization-reviewer",[3663,1127],[821,820],"Understand how AI agents can use connected accounts without receiving credentials",{"title":3675,"description":3841},"articles\u002Fhow-ai-agents-use-accounts-safely",[3854,3855,3856],"AI agent security","credentials","local software","JKPu-Jdna2W9Qq2agRudb6iN7TYk8OtG2zG3YTnp7yE",{"id":3859,"title":3860,"author":6,"body":3861,"category":4017,"description":4018,"extension":804,"featured":805,"heroImage":806,"meta":4019,"navigation":805,"path":4020,"publishedAt":3660,"readingTime":4021,"relatedAgents":4022,"relatedArticles":4023,"relatedWorkflows":4025,"searchIntent":4027,"seo":4028,"stem":4029,"topics":4030,"updatedAt":809,"visual":847,"__hash__":4033},"articles\u002Farticles\u002Fuse-codex-claude-gemini-with-existing-tools.md","How to use Codex, Claude Code, or Gemini CLI with the tools you already have",{"type":8,"value":3862,"toc":4009},[3863,3866,3869,3873,3877,3880,3883,3887,3890,3893,3910,3913,3932,3936,3939,3942,3946,3949,3952,3956,3959,3980,3983,3987,3990,3995,3998],[11,3864,3865],{},"You do not need to rebuild your operating setup around whichever AI client you use today. Keep Codex, Claude Code, or Gemini CLI as the place where you direct the work. Connect that client to StackOS through MCP, then let StackOS connect the work to the business systems it actually touches.",[11,3867,3868],{},"The AI chooses the next step. StackOS stores the plan, scopes the tool call, and records what happened. Credentials stay inside the StackOS daemon; the client receives safe references and the result it needs, not your login secrets.",[844,3870],{"caption":3871,"mode":847,"title":3872},"Each supported client can reach the same durable project state and the tools available to complete the work.","Keep the AI client. Keep the apps.",[21,3874,3876],{"id":3875},"why-keep-the-ai-client-separate","Why keep the AI client separate?",[11,3878,3879],{},"AI clients improve quickly, and people have different preferences. One person may work in Codex, another in Claude Code, and another in Gemini CLI. Locking the operating process to one chat interface makes switching expensive and fragments the work.",[11,3881,3882],{},"A shared work layer does not make the clients identical or copy private chat history between them. It gives each compatible client access to the same project record: workflows, run plans, dependencies, evidence, connected tools, and audit history.",[21,3884,3886],{"id":3885},"what-does-the-connection-look-like","What does the connection look like?",[11,3888,3889],{},"MCP is the connection layer. StackOS install and repair register a local MCP bridge with the supported clients found on your Mac. Codex, Claude Code, and Gemini CLI still keep their own MCP settings; those settings point to the same local StackOS runtime.",[11,3891,3892],{},"From there, the path is concrete:",[151,3894,3895,3898,3901,3904,3907],{},[57,3896,3897],{},"The client starts a StackOS session from the directory where you are working.",[57,3899,3900],{},"StackOS resolves that directory to its bound project instead of guessing from the last project someone used.",[57,3902,3903],{},"The AI inspects the relevant workflow or current run and chooses the next step.",[57,3905,3906],{},"That step receives only the context and tools its contract allows.",[57,3908,3909],{},"StackOS validates the call, performs the specific action, and records the result.",[11,3911,3912],{},"Human approval is not a default stage in this path. A client may still apply its own tool-confirmation settings, but StackOS does not add a blanket human checkpoint. The agent should ask when the request leaves intent, authority, a disclosure boundary, or a consequential choice unresolved.",[11,3914,3915,3916,1371,3921,3926,3927,3647],{},"This works because all three clients support MCP, although their configuration differs. See the official setup references for ",[32,3917,3920],{"href":3918,"rel":3919},"https:\u002F\u002Flearn.chatgpt.com\u002Fdocs\u002Fextend\u002Fmcp#connect-codex-to-an-mcp-server",[300],"Codex",[32,3922,3925],{"href":3923,"rel":3924},"https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fmcp",[300],"Claude Code",", and ",[32,3928,3931],{"href":3929,"rel":3930},"https:\u002F\u002Fgithub.com\u002Fgoogle-gemini\u002Fgemini-cli\u002Fblob\u002Fmain\u002Fdocs\u002Ftools\u002Fmcp-server.md",[300],"Gemini CLI",[21,3933,3935],{"id":3934},"does-stackos-replace-automation-tools","Does StackOS replace automation tools?",[11,3937,3938],{},"Your existing app remains the system of record. A content team can keep WordPress, a commerce team can keep Shopify, and an engineering team can keep GitHub.",[11,3940,3941],{},"StackOS keeps the execution context between the request and those tools: which project and workflow apply, which step is running, what that step may do, which dependencies are unresolved, what evidence supports the result, and what action was recorded.",[21,3943,3945],{"id":3944},"what-happens-when-you-change-models","What happens when you change models?",[11,3947,3948],{},"Another client does not inherit the private conversation from the old one. It connects from the same workspace, resolves the same StackOS project, and recovers the durable state: the current plan, completed steps, decisions, evidence, and next actions.",[11,3950,3951],{},"Each client still needs its own MCP registration. StackOS install and repair handle that registration for supported hosts, while the project state and business-tool connections remain in one place.",[21,3953,3955],{"id":3954},"a-simple-example","A simple example",[11,3957,3958],{},"Suppose you ask Codex to investigate customer feedback and prepare a fix.",[151,3960,3961,3968,3971,3974,3977],{},[57,3962,3963,3964,3647],{},"Codex starts StackOS from the project workspace and opens the relevant ",[32,3965,3967],{"href":3966},"\u002Flibrary\u002Fworkflows\u002Fcommunications-customer-feedback-intake","customer feedback workflow",[57,3969,3970],{},"StackOS creates a run plan and gives the intake step its bounded communication context and tools.",[57,3972,3973],{},"Codex investigates the feedback and records the findings with their evidence.",[57,3975,3976],{},"If delivery is in scope and the handoff criteria are met, Codex hands the result to a tracked delivery workflow with its dependencies intact.",[57,3978,3979],{},"If you later continue in Claude Code, it resolves the same project and can see what finished, what remains, and why.",[11,3981,3982],{},"The same pattern works when the starting client is Claude Code or Gemini CLI. The interface changes; the durable work contract does not.",[21,3984,3986],{"id":3985},"what-do-you-need-to-get-started","What do you need to get started?",[11,3988,3989],{},"Install StackOS on your Mac, then open a supported client from the real project directory. Confirm that the StackOS MCP connection is healthy and make one bounded request, for example:",[2224,3991,3992],{},[11,3993,3994],{},"Use StackOS for this workspace. Show me the relevant workflow and the first executable step.",[11,3996,3997],{},"Connect the one outside app that request needs. Do not start by wiring every tool your company owns. One real workflow will expose the missing context, permissions, and handoffs much faster.",[11,3999,4000,4001,4003,4004,4008],{},"Browse the ",[32,4002,3831],{"href":3830}," to choose a starting point, or ",[32,4005,4007],{"href":4006},"\u002F#install","download StackOS for Mac"," and connect the client you already use.",{"title":104,"searchDepth":215,"depth":215,"links":4010},[4011,4012,4013,4014,4015,4016],{"id":3875,"depth":215,"text":3876},{"id":3885,"depth":215,"text":3886},{"id":3934,"depth":215,"text":3935},{"id":3944,"depth":215,"text":3945},{"id":3954,"depth":215,"text":3955},{"id":3985,"depth":215,"text":3986},"Getting started","Keep your preferred AI client and existing business apps. Connect each client to the same durable project so plans, tool access, credentials, and receipts do not disappear with the chat.",{},"\u002Farticles\u002Fuse-codex-claude-gemini-with-existing-tools","7 min read",[],[1127,4024],"how-ai-agents-use-accounts-safely",[4026,821],"communications-customer-feedback-intake","Learn how to connect an existing AI client to existing business tools",{"title":3860,"description":4018},"articles\u002Fuse-codex-claude-gemini-with-existing-tools",[3920,3925,3931,4031,4032],"MCP","AI tools","kZJ6ff8HrH3N333-Z9-ulIFArx9mw_SiXwk4VWkGbi8",{"id":4035,"title":4036,"author":6,"body":4037,"category":4307,"description":4308,"extension":804,"featured":805,"heroImage":806,"meta":4309,"navigation":805,"path":4310,"publishedAt":3660,"readingTime":1122,"relatedAgents":4311,"relatedArticles":4313,"relatedWorkflows":4314,"searchIntent":4316,"seo":4317,"stem":4318,"topics":4319,"updatedAt":809,"visual":829,"__hash__":4321},"articles\u002Farticles\u002Fwhat-is-an-agentic-workflow.md","What is an agentic workflow? A practical guide to AI-powered work",{"type":8,"value":4038,"toc":4297},[4039,4042,4045,4048,4051,4055,4058,4061,4075,4078,4082,4085,4123,4126,4130,4133,4153,4156,4159,4163,4166,4169,4172,4175,4179,4241,4244,4248,4251,4268,4271,4275,4278,4281,4285,4288],[11,4040,4041],{},"An agentic workflow is a durable execution structure in which AI interprets a goal, chooses the next valid action, uses scoped context and tools, and records the result until the acceptance criteria are met.",[11,4043,4044],{},"The workflow becomes agentic at its decision points. The AI may decide which evidence matters, whether a planned step is still necessary, how to recover from a failed check, or which reviewer finding belongs in the work. State storage, grant enforcement, payload validation, and audit records can remain mechanical.",[11,4046,4047],{},"That separation is useful because adding a model to a fixed chain does not automatically make the work agentic.",[3154,4049],{"title":4050,"workflow":820},"A complete content workflow, from request to verified result",[21,4052,4054],{"id":4053},"what-makes-a-workflow-agentic","What makes a workflow agentic?",[11,4056,4057],{},"Fixed automation follows a known mapping: when this happens, do that. An agentic workflow is useful when the next valid action depends on meaning, evidence, or a changing situation.",[11,4059,4060],{},"Consider four decisions from a content workflow:",[54,4062,4063,4066,4069,4072],{},[57,4064,4065],{},"Is an operator interview needed, or is the relevant experience already captured?",[57,4067,4068],{},"Does the evidence support the proposed angle?",[57,4070,4071],{},"Is a reviewer finding a blocker, a useful repair, a preference, or scope drift?",[57,4073,4074],{},"Has the article met its terminal condition, or is a material claim still unresolved?",[11,4076,4077],{},"Those decisions need reasoning. The workflow still bounds the reasoning with named state, allowed actions, expected outputs, and a stopping rule. Human input is reserved for materially missing intent, authority, disclosure, or a consequential choice; it is not a checkpoint added to every stage.",[21,4079,4081],{"id":4080},"what-should-the-workflow-contain","What should the workflow contain?",[11,4083,4084],{},"A practical agentic workflow needs six things:",[151,4086,4087,4093,4099,4105,4111,4117],{},[57,4088,4089,4092],{},[671,4090,4091],{},"Problem and outcome."," Name the failure, friction, or decision AI should help with, the useful result, and the side-effect boundary.",[57,4094,4095,4098],{},[671,4096,4097],{},"State and dependencies."," Record what is pending, active, accepted, blocked, or complete, and which later work depends on it.",[57,4100,4101,4104],{},[671,4102,4103],{},"Context, tools, and authority."," Give each step the information and operations it needs without exposing unrelated history or broader access.",[57,4106,4107,4110],{},[671,4108,4109],{},"Decision ownership."," State what the orchestrator decides and which bounded responsibilities belong to specialist agents.",[57,4112,4113,4116],{},[671,4114,4115],{},"Outputs, evidence, and acceptance."," Define what each step must return, which claims need support, and how the result will be verified.",[57,4118,4119,4122],{},[671,4120,4121],{},"Recovery and a terminal condition."," Provide the next safe action for anticipated failures and a concrete definition of done.",[11,4124,4125],{},"These do not need to become six long prompt sections. Stable rules can stay in the workflow, project state, and tool contracts. The agent should receive the subset that changes its next decision.",[21,4127,4129],{"id":4128},"what-happens-from-request-to-result","What happens from request to result?",[11,4131,4132],{},"Imagine an operator asks a tool-using AI client to turn research and firsthand experience into an article. The conversation is only the starting point.",[151,4134,4135,4138,4141,4144,4147,4150],{},[57,4136,4137],{},"The AI interprets the request, selects the relevant workflow, and adapts a concrete run plan for the topic, sources, channel, image intent, and publication boundary.",[57,4139,4140],{},"The orchestrator reads the current state and chooses the next eligible step. It supplies the context and tools that step needs.",[57,4142,4143],{},"Research, writing, and review agents handle bounded responsibilities. They return evidence, drafts, or findings rather than taking over the whole job.",[57,4145,4146],{},"StackOS stores the plan, scopes each tool call, validates execution, and records the result. It does not choose the content strategy.",[57,4148,4149],{},"The orchestrator adjudicates review findings against the accepted angle and evidence. Not every suggestion enters delivery.",[57,4151,4152],{},"The run ends when the requested artifact exists, material claims are supported or explicitly unresolved, blocking findings are repaired, and verification passes. Publication runs only when it was requested and authorized.",[11,4154,4155],{},"The durable state matters as much as the steps. If research is incomplete, later work stays blocked. If a tool call fails, the receipt shows what happened. If the session changes, the next agent can recover the accepted state without replaying the whole conversation.",[11,4157,4158],{},"This is the model we are building and using in StackOS: the AI chooses the next step; StackOS persists the contract and execution record.",[21,4160,4162],{"id":4161},"where-does-the-agentic-judgment-belong","Where does the agentic judgment belong?",[11,4164,4165],{},"Our early mistake was to treat “agentic” as a reason to add more agents. Running the workflows exposed a different problem.",[11,4167,4168],{},"Fresh agents could often work around missing context. They read more files, inspected more tools, and reconstructed earlier decisions. They reached the result, but the workflow was spending their reasoning on state the system already knew.",[11,4170,4171],{},"Reviewers created another signal. They could always propose one more improvement. When the orchestrator accepted each suggestion, the job drifted beyond the agreed plan.",[11,4173,4174],{},"The useful refinements were clearer handoffs and stronger gatekeeping. Agents still reason about the work. The workflow carries known state, and the orchestrator decides which findings belong in delivery.",[21,4176,4178],{"id":4177},"how-is-this-different-from-a-chatbot-or-fixed-automation","How is this different from a chatbot or fixed automation?",[314,4180,4181,4197],{},[317,4182,4183],{},[320,4184,4185,4188,4191,4194],{},[323,4186,4187],{},"Mode",[323,4189,4190],{},"Best for",[323,4192,4193],{},"How it adapts",[323,4195,4196],{},"What marks completion",[333,4198,4199,4213,4227],{},[320,4200,4201,4204,4207,4210],{},[338,4202,4203],{},"Conversation",[338,4205,4206],{},"A question, explanation, or one-off draft",[338,4208,4209],{},"The model responds within the current context",[338,4211,4212],{},"A useful response is returned",[320,4214,4215,4218,4221,4224],{},[338,4216,4217],{},"Fixed automation",[338,4219,4220],{},"A stable trigger with a known action",[338,4222,4223],{},"Predetermined rules and branches",[338,4225,4226],{},"The configured action finishes",[320,4228,4229,4232,4235,4238],{},[338,4230,4231],{},"Agentic workflow",[338,4233,4234],{},"Multi-step work where evidence or state changes the next action",[338,4236,4237],{},"An agent reasons within a durable execution contract",[338,4239,4240],{},"Acceptance criteria and verification pass",[11,4242,4243],{},"A conversation can call tools, and fixed automation can have many branches. The difference is whether the job needs adaptive judgment plus durable state across the run.",[21,4245,4247],{"id":4246},"where-can-agentic-workflows-be-used","Where can agentic workflows be used?",[11,4249,4250],{},"Use an agentic workflow when:",[54,4252,4253,4256,4259,4262,4265],{},[57,4254,4255],{},"the outcome spans several dependent stages or sessions;",[57,4257,4258],{},"the next step depends on evidence rather than a fixed rule;",[57,4260,4261],{},"different responsibilities need different context or independent review;",[57,4263,4264],{},"connected tools have side effects that require narrow authority and receipts;",[57,4266,4267],{},"failure needs recovery and continuation rather than a full restart.",[11,4269,4270],{},"In engineering, test evidence may change the next implementation step. In content, source quality may change the angle and reviewer feedback must be gated against the brief. In support, an investigation may end in an answer or a structured delivery handoff. The domain changes; the operating problem is the same.",[21,4272,4274],{"id":4273},"when-should-you-use-one","When should you use one?",[11,4276,4277],{},"Do not build one for every request. A normal conversation is enough for a quick question or one-off draft. Fixed automation is usually better for a deterministic transformation. A single explicit tool action does not need a ten-step workflow around it.",[11,4279,4280],{},"The workflow earns its cost when the work needs both judgment and continuity.",[21,4282,4284],{"id":4283},"the-shortest-useful-definition","The shortest useful definition",[11,4286,4287],{},"An agentic workflow is durable, goal-directed work in which AI chooses the next valid action inside explicit boundaries for state, authority, evidence, verification, recovery, and completion.",[11,4289,4290,4291,4294,4295,3647],{},"For the surrounding roles, see ",[32,4292,4293],{"href":2901},"AI agent vs. workflow vs. orchestrator",". For the execution experience each agent needs, see ",[32,4296,1076],{"href":1075},{"title":104,"searchDepth":215,"depth":215,"links":4298},[4299,4300,4301,4302,4303,4304,4305,4306],{"id":4053,"depth":215,"text":4054},{"id":4080,"depth":215,"text":4081},{"id":4128,"depth":215,"text":4129},{"id":4161,"depth":215,"text":4162},{"id":4177,"depth":215,"text":4178},{"id":4246,"depth":215,"text":4247},{"id":4273,"depth":215,"text":4274},{"id":4283,"depth":215,"text":4284},"Agentic workflows","An agentic workflow lets AI choose the next valid action inside a durable contract for state, tools, evidence, verification, recovery, and completion.",{},"\u002Farticles\u002Fwhat-is-an-agentic-workflow",[4312,1125],"branding-evidence-curator",[3133,3663],[821,820,4315],"marketing-campaign-production","Understand what an agentic workflow is, how it works, and when to use one",{"title":4036,"description":4308},"articles\u002Fwhat-is-an-agentic-workflow",[3671,3669,4320],"workflow automation","mbFfmMr5UmamUPIjJxDTFSLWo4Kp0tpi4Evlz5cKBHQ",1783930557731]