Agents, part 1: how agents work and how much autonomy a task needs
What is an agent, how does it work under the hood, and how much autonomy does my task need?
An assistant can explain how to fix a broken link. An agent can inspect the repository, find the target, edit the link, run a check, and return a reviewable change. The useful difference is the feedback loop: the system observes what happened and chooses what to do next.
This three-part series follows that loop from first use to operation. Start here if you have used a chatbot but have not built an agent. Basic familiarity with files and commands is enough.
| Read | The question it answers |
|---|---|
| 1 · How agents work | What is an agent, how does it work, and how much autonomy does my task need? |
| 2 · Skills and harnesses | How do I package a procedure and build a loop whose completion I can verify? |
| 3 · Operating an agent harness | How do I run an agent day to day: sessions, permissions, memory, schedules and recovery? |
The main text describes mechanisms that do not depend on one vendor. Named products, protocol versions and recent research directions are collected in Current options, with the date they were checked.
Key points
- An agent is a model inside a loop: it proposes an action, code executes it, and the observation shapes the next proposal.
- The model never runs a tool itself. It emits a structured request; your harness decides whether that request may run.
- Every request re-sends the instructions, tool definitions, conversation and tool results. The context window is a budget, and tool results are usually what exhausts it.
- Most agent failures are system failures: missing evidence, an ambiguous tool, an unbounded result, an unchecked completion claim.
- Choose the smallest system that meets the task’s acceptance check. A fixed workflow often beats a free-running agent.
- Write a task contract (goal, inputs, allowed actions, acceptance test, stop condition) before choosing any tool.
Start with the work you want finished
Consider a weekly literature digest. A useful outcome is a local document with a short description of each selected paper, a primary-source link, and an explicit list of uncertainties. “Research everything about agents” leaves the search space and the completion test open. “Prepare this digest from these sources, then stop before sending it” gives the system a task it can finish.
The same principle applies to code. Specify the observable behavior, the allowed files, a validation command, and the artifact you expect. Here is an original task template you can adapt:
Code · 7 lines
Goal: prepare a short digest of the three supplied papers.
Inputs: the supplied PDFs and their official publication pages.
Output: a local draft with a claim, evidence, limitation, and source for each.
Allowed actions: read these sources and write inside the draft directory.
Acceptance: every factual claim has a source; unknowns remain explicit.
Stop: after the draft and source checks; do not send or publish it.
If blocked: preserve completed work and name the missing evidence.This is a task contract, not a magic prompt. Prompt text cannot enforce permissions; the application must enforce file-system and sending limits in its tools. Choose a first task with a small output and an obvious check, then review the artifact and the checks rather than the confidence of the final message.
The parts of an agent
The model proposes actions. Tools let it read or change the environment. Context supplies the current task and evidence. The harness is the surrounding runtime that manages the loop, executes tools, keeps state, enforces limits and recovers from errors. A skill packages reusable task knowledge that the runtime can load when relevant. These roles can live in one program; they remain useful distinctions when debugging. [4, 5, 6]

Suppose a digest cites the wrong paper. Ask where the error entered. Was the source absent from context? Did search return a similarly named article? Did a tool truncate the relevant passage? Did the checker verify only that a URL existed? Each cause needs a different fix; rewriting the system prompt may leave the real failure untouched.
How tool calling actually works
Plain version. The model cannot click, read files or call APIs. It writes a structured request saying which tool it wants and with what arguments. Your code reads that request, decides whether to run it, runs it, and sends the result back in the next request.
Precise version. Major model APIs implement the same round trip, with different field names. [12, 13]
- The application sends a request containing the conversation and a list of tool definitions. Each definition has a name, a natural-language description and a JSON Schema for the arguments.
- Instead of (or besides) text, the model returns one or more tool calls: a tool name, arguments, and an identifier for each call. The response is marked as stopping for tool use.
- The application validates the arguments, checks authorization, and executes the call.
- The application sends a second request that repeats the earlier messages, includes the model’s tool call, and adds a tool result that carries the same identifier.
- The model reads the result and either answers or requests another call. An agent loop repeats steps 2–5 until the model stops or the harness stops it.

Four consequences follow directly from this mechanism:
- Execution is your decision. Because the model only proposes, authorization, sandboxing and argument checks belong in code. A provider can also run some tools on its own servers (for example web search); those are a separate category with their own controls. [12]
- Schemas reduce, but do not remove, argument errors. Both providers offer a strict mode that constrains arguments to the declared schema. A schema-valid argument can still be the wrong value: a well-formed date for the wrong day. [12, 13]
- Identifiers pair calls with results. When a model issues several calls in one turn, the identifiers tell it which result belongs to which call. A harness that loses or reorders them corrupts the history. [12, 13]
- Tool descriptions are prompts. The model selects tools from their names and descriptions. Overlapping tools, vague parameter names (
userinstead ofuser_id) and opaque error messages cause wrong calls. Clear namespacing, few high-value tools, bounded outputs and errors that say how to fix the input measurably help. [16]
The context window is a budget
Plain version. The model has no memory between requests. Everything it should know must be inside the current request, and that request has a maximum size.
Precise version. The context window is the number of tokens a model can attend to in one request, including the output it generates. The system prompt, every message, every tool definition and every tool result count toward it, and both providers bill tool definitions as input tokens. [12, 13, 14] Each new step of an agent re-sends the accumulated history, so the window fills step by step. A larger window is not a cure: recall can degrade as context grows, and information in the middle of a long input can be used less reliably than information at the beginning or end. [14, 15]
A small calculation shows why tool output dominates. The snippet below uses assumed sizes (a 200,000-token window, 16,000 tokens reserved for output, 9,000 tokens of fixed instructions and tool definitions, 400 tokens of model text per step). It counts how many tool-using steps fit before the next request would overflow:
Code · Python · 19 lines
WINDOW = 200_000 # assumed context window, in tokens
RESERVED_OUTPUT = 16_000 # room kept free for the model's reply
FIXED = 3_000 + 6_000 # system instructions + tool definitions, sent every call
def calls_before_full(result_tokens, per_call_overhead=400, cap=None):
"""Count model calls until the next request would not fit."""
used, calls = FIXED, 0
while True:
result = result_tokens if cap is None else min(result_tokens, cap)
nxt = used + per_call_overhead + result
if nxt + RESERVED_OUTPUT > WINDOW:
return calls
used, calls = nxt, calls + 1
for size in (500, 5_000, 20_000):
print(f"{size:>6,}-token results: {calls_before_full(size):>3} calls uncapped,"
f" {calls_before_full(size, cap=2_000):>3} calls capped at 2,000")Code · 3 lines
500-token results: 194 calls uncapped, 194 calls capped at 2,000
5,000-token results: 32 calls uncapped, 72 calls capped at 2,000
20,000-token results: 8 calls uncapped, 72 calls capped at 2,000The numbers are assumptions, but the shape is general: an uncapped tool that returns a long file or a search page exhausts a large window in a handful of steps. The levers, in rough order of how early to reach for them:
- Bound every tool result. Paginate, filter and truncate with an explicit marker, and keep the full output on disk with a path back to it. [5, 16]
- Retrieve on demand. Search, then open the relevant passage, rather than pasting whole documents in advance.
- Load tools and procedures on demand. Tool search and skills keep rarely used definitions out of every request. [6, 11]
- Compact. Summarize older turns and keep recent ones verbatim. Compaction can drop the qualification that made a result valid, so keep the originals retrievable. [5, 14]
- Externalize state. Write progress, decisions and open questions to files that a later step or session can read. [7]
How the field got here
The dates below mark representative publications and engineering reports, not the invention of each idea.
2022–2023: language connected to actions. ReAct interleaves reasoning steps with actions, so observations can change the next decision; its experiments show why retrieving information during a task can beat answering from the first prompt alone. [1] Toolformer studies teaching a model when to call APIs through self-supervised training, a different layer from passing tool definitions to an already trained model. [2] Reflexion carries textual feedback between attempts without changing weights; feedback is useful, but it is not an independent correctness test. [3]
2024: workflows as a design choice. Anthropic’s Building effective agents separates predefined workflows from systems where the model chooses its next steps, and catalogs routing, parallel work and evaluator loops as patterns to select for a task. [4]
2025: context and reusable procedures. As tasks lengthened, the central question became what information survives between steps: selective retrieval, compaction, skills loaded on demand, and handoff artifacts for multi-session work. [5–7]
2026: the environment as a first-class component. Engineering reports emphasize readable repositories, machine-checkable constraints, separate planning/generation/evaluation roles, and decoupling session history from the execution environment. These are case studies, not benchmark guarantees. [8–10]
The durable lesson across all four periods: make work inspectable. The next step, or the next session, should be able to find the objective, the current files, the remaining failures and evidence of completed checks.
Choose the smallest system that fits
| Situation | A useful starting point | The deciding check |
|---|---|---|
| Explain or rewrite supplied text | A single model call | Does the response meet a rubric? |
| Predictable steps and input format | A fixed workflow with validation | Do the intermediate schemas and final artifact pass? |
| Failures require investigation and changing tactics | One agent with a bounded tool loop | Can it recover from a representative failure? |
| Independent investigations to combine | Parallel workers with an output contract | Does integration improve the result enough to pay for it? |
| Work spans restarts or external events | Persistent sessions, scheduled or event-driven runs | Can it resume without repeating a side effect? |
This is a design recommendation, not a performance ranking. Parallelism helps only when work is independent; two agents editing one file spend their time resolving each other’s changes. A separate reviewer catches omissions, but two models can share the same wrong assumption, so prefer executable or source-based checks. [4, 9] Agent workflows treats these patterns in detail.
Where agents fail
| Failure | What it looks like | Usual root cause | First fix |
|---|---|---|---|
| Wrong tool or wrong argument | Searches the wrong system; edits the wrong file | Overlapping tool descriptions; ambiguous parameters | Fewer, namespaced tools; examples in descriptions [16] |
| Invented argument | Fills a required field the user never gave | Missing input; prompt rewards completion | Ask-for-input path; validation that rejects defaults [12] |
| Context overflow or decay | Forgets an early constraint; truncation errors | Unbounded tool results; long history | Bounded results, compaction, external notes [5, 14] |
| Loop without progress | Repeats the same failing command | No budget; no detection of repeated failure | Step and cost budgets; stop on repeated identical failures |
| Injected instructions | Follows a command found inside a web page or file | Untrusted content treated as instructions | Least privilege, labelled untrusted content, approval for risky actions [24] |
| False completion | “Done” while tests fail or nothing changed | Completion judged from the transcript | Check the environment; gate completion on evidence (part 2) |
Indirect prompt injection deserves a separate note: when an agent reads external content, that content can contain text phrased as instructions. Filtering helps but is not a guarantee, so the robust controls are structural: limit what tools and credentials the agent holds, keep untrusted content labelled, and require approval at new, risky boundaries. [23, 24]
Interfaces live at different layers
| Name | Main concern | It does not by itself provide |
|---|---|---|
| Agent Skills | Portable task instructions and supporting files | New credentials or guaranteed execution |
| MCP (Model Context Protocol) | Connecting an application to tools, resources and prompts from servers | A task plan or a complete agent runtime |
| ACP (Agent Client Protocol) | Communication between editors/clients and coding agents | A universal policy for all actions |
| A2A (Agent2Agent) | Communication and task collaboration between agent systems | Shared private state or automatic mutual trust |
These descriptions follow the primary specifications. They are complementary interfaces, not competing names for one product, and compatibility depends on the versions and capabilities both ends support. The MCP specification itself states that it cannot enforce consent or tool safety at the protocol level; the host application must. [6, 20–22] You do not need any of them to run one useful agent.
Your first useful experiment
Choose a task you already know how to check. Run a simple baseline, then change one part of the system: add a relevant skill, cap a tool’s output, improve an error message, or supply a missing source. Compare the output and the amount of human correction. Keep the failed examples.
For the digest, try a paper with an ambiguous title, a missing PDF, and a source that contradicts an earlier summary. Useful behavior is resolving the ambiguity or reporting the gap; filling every table cell is not success if the evidence is absent.
You are ready for the next part when you can name the expected artifact, allowed actions, completion check and stop condition. Continue to skills and harnesses, or to operating an agent harness if you already run one.
Current options, checked 6 November 2026
This section collects details that change with releases. The main text above does not depend on them.
Protocol versions. The MCP specification’s current version is dated 2026-07-28; it defines servers offering tools, resources and prompts over JSON-RPC 2.0, with optional extensions such as long-running tasks. [20] The Agent Skills specification is a living document; its allowed-tools field is marked experimental. [6] ACP and A2A publish living documentation; check the version both ends implement. [21, 22]
Context limits. As one concrete example, Anthropic’s current model documentation lists 1M-token context windows for its current models, counts tool definitions and results toward the window, and offers server-side compaction. Other providers publish their own limits and behaviors. [14]
Directions worth following. These are recent research or engineering proposals, not settled practice:
- Programmatic tool calling moves filtering, loops and aggregation into code that the model writes, so the model receives only the result that matters. The execution environment still needs controls. [11, 19]
- Recursive Language Models (RLMs) treat a long input as an environment to inspect and decompose through programmatic, recursive calls, rather than pasting it into one larger window. [18]
- Reflective prompt optimization such as GEPA evolves prompts from trajectory feedback; its comparisons are task-specific. Keep the cases used for tuning separate from the cases used for judging. [17]
- Long-running harness designs separate planning, generation and evaluation, and decouple session history from execution sandboxes. [9, 10]
Further reading
- Anthropic, Building effective agents: the clearest taxonomy of workflow versus agent patterns. [4]
- Anthropic and OpenAI tool-use guides (tool use, function calling): the exact request/response shapes of the round trip. [12, 13]
- Effective context engineering for AI agents: selecting, compressing and externalizing context. [5]
- Liu et al., Lost in the Middle: why more context is not automatically better context. [15]
- Yao et al., ReAct: the paper that made the observe–act loop concrete. [1]
- OWASP, LLM01:2025 Prompt Injection: the threat that every tool-using agent must design around. [24]
References
- Shunyu Yao et al., “ReAct: Synergizing Reasoning and Acting in Language Models,” ICLR, 2023; initial preprint 2022. Paper.
- Timo Schick et al., “Toolformer: Language Models Can Teach Themselves to Use Tools,” NeurIPS, 2023. Paper.
- Noah Shinn et al., “Reflexion: Language Agents with Verbal Reinforcement Learning,” NeurIPS, 2023. Paper.
- Anthropic, “Building effective agents,” engineering article, 19 December 2024. Article.
- Prithvi Rajasekaran et al., “Effective context engineering for AI agents,” Anthropic, 29 September 2025. Article.
- Agent Skills contributors, “Specification,” living specification, accessed 6 November 2026. Specification.
- Anthropic, “Effective harnesses for long-running agents,” engineering article, 26 November 2025. Article.
- Ryan Lopopolo, “Harness engineering: leveraging Codex in an agent-first world,” OpenAI, 11 February 2026. Article.
- Prithvi Rajasekaran, “Harness design for long-running application development,” Anthropic, 24 March 2026. Article.
- Anthropic, “Scaling Managed Agents: Decoupling the brain from the hands,” 8 April 2026. Article.
- Anthropic, “Introducing advanced tool use on the Claude Developer Platform,” 24 November 2025. Article.
- Anthropic, “Tool use with Claude,” Claude Platform documentation, accessed 6 November 2026. Documentation.
- OpenAI, “Function calling,” OpenAI API documentation, accessed 6 November 2026. Documentation.
- Anthropic, “Context windows,” Claude Platform documentation, accessed 6 November 2026. Documentation.
- Nelson F. Liu et al., “Lost in the Middle: How Language Models Use Long Contexts,” Transactions of the Association for Computational Linguistics, 2024. Paper.
- Ken Aizawa, “Writing effective tools for AI agents,” Anthropic, 11 September 2025. Article.
- Lakshya A. Agrawal et al., “GEPA: Reflective Prompt Evolution Can Outperform Reinforcement Learning,” ICLR, 2026. Paper.
- Alex L. Zhang, Tim Kraska and Omar Khattab, “Recursive Language Models,” arXiv:2512.24601, 2025, revised May 2026. Paper.
- Anthropic, “Code execution with MCP: Building more efficient agents,” 4 November 2025. Article.
- Model Context Protocol contributors, “Specification” (version 2026-07-28) and “Architecture overview,” accessed 6 November 2026. Specification, architecture.
- Agent Client Protocol contributors, “Introduction,” living documentation, accessed 6 November 2026. Documentation.
- A2A contributors, “What is A2A?,” living documentation, accessed 6 November 2026. Documentation.
- Kai Greshake et al., “Not What You’ve Signed Up For: Compromising Real-World LLM-Integrated Applications with Indirect Prompt Injection,” Proceedings of the 16th ACM Workshop on Artificial Intelligence and Security, 2023. DOI, preprint.
- OWASP Gen AI Security Project, “LLM01:2025 Prompt Injection,” OWASP Top 10 for LLM Applications 2025. Entry.