Files

T

retoor afc88b8087 ask_user tool, prompt-JSON CLI repair loop, tool-loop research archive

- New ask_user core tool: mid-turn user question with option picking,
  refusing cleanly in autonomous mode, for background workers, and
  without a tty; system prompt points at it instead of prose questions.
- Structural loop control for prompt-JSON CLI backends (opencode,
  grok, claude, codex, gemini): shared cli_json_turn repairs a
  missing JSON envelope exactly once, then accepts prose; prompt
  contract hardened against narrate-without-calling.
- research/agentic-tool-loop-design: 74 sources plus 2 conclusions
  backing the loop-control decisions; INDEX updated to 6 subjects.

2026-10-11 02:54:17 +02:00

3.7 KiB

Raw Blame History

Building Effective Agents

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	agentic-tool-loop-design
Document type	Source Dossier
Tier	1
Source title	Building effective agents
Source URL	https://www.anthropic.com/engineering/building-effective-agents
Source publisher / author	Anthropic Engineering (Erik S. and Barry Zhang)
Source type	blog post
Source date (published)	2024-12-19
Date researched	2026-10-11
Researched by	tai (agent), model: Muse Spark, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

Anthropic's canonical engineering post on agentic systems, drawn from work with dozens of teams. It distinguishes workflows (predefined code paths) from agents (LLMs dynamically directing their own tool use), argues for starting with the simplest pattern that works, and defines the autonomous agent as typically just an LLM using tools in a loop driven by environmental feedback, with stopping conditions such as maximum iterations. Appendix 2 gives tool-design rules: formats close to what the model has seen in training data, no formatting overhead, and agent-computer interface effort equal to HCI effort.

Key findings

Agents are defined as systems where LLMs dynamically direct their own processes and tool usage; implementation is often straightforward: LLMs using tools based on environmental feedback in a loop.
During execution the agent must gain ground truth from the environment at each step (tool call results, code execution) to assess progress; tasks often terminate on completion but commonly also include stopping conditions such as a maximum number of iterations.
Three core principles for agents: simplicity of design, transparency of planning steps, and careful tool documentation and testing (the agent-computer interface, ACI).
Tool format guidance: give the model tokens to think before committing, keep formats close to naturally occurring text, avoid formatting overhead such as pre-counting changed lines or string-escaping code inside JSON.
A good tool definition includes example usage, edge cases, input format requirements, and clear boundaries from other tools; poka-yoke tools so mistakes are hard (example: requiring absolute file paths fixed relative-path errors in their SWE-bench agent).
More time was spent optimizing tools than the overall prompt in their SWE-bench agent.

Pros / strengths

Written from production experience across many deployments, not a toy demo; recommendations are concrete and falsifiable.
The workflows-vs-agents taxonomy gives a clean vocabulary for deciding how much autonomy a task needs.
Appendix 2 is directly actionable for tool-schema design.

Cons / limitations / caveats

Dated December 2024; the page itself notes the tooling landscape has changed and points to newer Managed Agents material.
Says little about the failure mode of weak models narrating instead of calling tools, since it assumes frontier models with native tool use.
No discussion of approval/permission tiers for destructive actions.

Relevance to tai

Directly load-bearing for the loop-control conclusion: tai's Agent.run_turn (loop while tool calls arrive, stop on plain content, bounded by step caps and stall detection) already matches the canonical agent shape this post describes; the fix belongs in the backend adapters and tool/prompt contracts, not in loop restructuring.
The ACI guidance (example usage, boundaries, poka-yoke) applies to tai's tool schemas and to the JSON contract given to prompt-based CLI backends.

Changelog

Date	Change
2026-10-11	Initial dossier created.

3.7 KiB Raw Blame History