---
title: "Reasoning | Elements of Agentic System Design"
description: "How calls and operations form loops and larger reasoning structures."
---

- [Idyllic Labs](https://idylliclabs.com/)

[Writing](https://idylliclabs.com/writing)

[Elements of Agentic System Design](https://idylliclabs.com/projects/elements-book)

Chapter 4, second edition working draft

# Reasoning

How calls and operations form loops and larger reasoning structures.

![A winding path returns around a central garden before reaching a higher terrace.](https://idylliclabs.com/images/elements-book/chapter-reasoning.png)

An agent loop uses the result of one action to choose the next step.

Contents

[Introduction](https://idylliclabs.com/projects/elements-book)

- [1. Context](https://idylliclabs.com/projects/elements-book/context)
- [2. Memory](https://idylliclabs.com/projects/elements-book/memory)
- [3. Agency](https://idylliclabs.com/projects/elements-book/agency)
- [4. Reasoning](https://idylliclabs.com/projects/elements-book/reasoning)[The Agent Loop](#the-agent-loop)[Composition](#composition-of-reasoning-structures)[Required stages](#model-decisions-and-required-stages)[Operations between model calls](#operations-between-model-calls)[Planning](#planning-and-revision)[Execution traces](#execution-traces-and-composition-costs)
- [5. Coordination](https://idylliclabs.com/projects/elements-book/coordination)
- [6. Artifacts](https://idylliclabs.com/projects/elements-book/artifacts)
- [7. Autonomy](https://idylliclabs.com/projects/elements-book/autonomy)
- [8. Evaluation](https://idylliclabs.com/projects/elements-book/evaluation)
- [9. Feedback](https://idylliclabs.com/projects/elements-book/feedback)
- [10. Learning](https://idylliclabs.com/projects/elements-book/learning)

A reasoning structure combines model calls and ordinary computation to solve a problem. A single call can compare, infer, and plan from the information in its context. When the next decision depends on a search result or the output of a program, the application must execute that operation and supply the result to another call. Agency gives us the connection between a decision and an action. Reasoning concerns how we arrange those decisions and actions into a process.

## The Agent Loop

The tool-calling agent loop is the central reasoning structure in an agentic system. The model receives a task and the observations collected so far, then chooses an action. The runtime executes the tool, records the result, and calls the model again with the updated context. The next call can choose another action or return an answer. This repeated cycle lets an agent work toward a result through a sequence of actions whose order need not be known in advance.

The following example handles one action at a time. The helpers represent application code, with an adapter handling the model provider's message format. `assembleContext` supplies the goal and relevant history, preserving each tool request with its result. The record can grow while the next input stays within the context window. `executeTool` validates the arguments, runs the handler, and returns the result as described in Agency.

```typescript
const trace = []

for (let step = 0; step < maxSteps; step++) {
  const context = assembleContext({ goal, trace, tools })
  const decision = await callModel(context)

  if (decision.kind === "answer") {
    return { status: "candidate", answer: decision.text }
  }

  const result = await executeTool(decision.toolCall)
  trace.push({ call: decision.toolCall, result })
}

return { status: "stopped", reason: "step limit" }
```

![An inset reasoning process sits inside a model call; an outer loop connects context, decision, tool execution, and observations.](https://idylliclabs.com/images/elements-book/reasoning-01.png)

The tool-calling agent loop connects a model decision to execution and observation. Each result supplies information for the next call.

Much of the control flow is implicit in the model's choice of the next action. The application does not need a separate branch for every search result or a predetermined sequence of tools. The model can decide that a claim needs another source, that a failed test requires an edit, or that the available evidence is sufficient. These judgments select the next operation within the same small loop. The requested actions remain explicit and recordable; the application has delegated the choice of their order to the model.

A trajectory is the sequence of decisions and observations produced during a run. Two runs of the same loop can take different trajectories toward the same task. A filing comparison may find the needed sources immediately and proceed to a draft. Conflicting sources may instead lead to a narrower query and more reading before drafting. The runtime repeats the same cycle in both cases; the observations and the model's interpretation determine which actions follow.

The loop aims to converge on a result: successive actions obtain missing information, resolve difficulties, and complete the task. Repetition alone does not guarantee that progress. An agent can revisit the same sources or stop before resolving an important question. The code therefore distinguishes a candidate answer from a run stopped by its step limit. Acceptance may still require a test, a review, or confirmation that an intended change occurred. Deadlines and cancellation can also stop execution without completing the task.

![A shared model-selection, application-execution, and observation cycle sits above two recorded trajectories for comparing filings. Run A searches, reads, and drafts. Run B encounters conflicting sources, refines its search, then reads and drafts. Each ends in a separate candidate result.](https://idylliclabs.com/images/elements-book/reasoning-08.png)

The runtime repeats the same cycle. Model decisions and returned observations determine the sequence of actions; either run still produces a candidate that may need checking.

## Composition

The agent loop is one way to compose calls. When the steps are already known, a sequence can be simpler: retrieve a document, extract the relevant passages, then write a summary. Each stage receives a defined input and produces something the next stage needs. Code chooses the order, so the model does not have to rediscover the procedure on every task.

Other arrangements support work that branches or has several dependencies:

- **Candidate search** explores several approaches before choosing one to continue. A tree can represent candidates that branch into further alternatives.
- **A directed acyclic graph (DAG)** expresses dependencies without a cycle. Two source sets can be examined separately, with synthesis waiting for both.
- **A routing branch** selects one path, such as sending a calculation to a code-execution step.

The choice follows how much of the process can be specified in advance. A pipeline fixes the stages; a tool-calling loop leaves the next operation open to model judgment. A graph combines dependent and independent stages. Any stage can itself contain a smaller structure, so a fixed research pipeline can include a search loop. An agent can also invoke a tool whose implementation runs a fixed pipeline. Composition lets us combine a known procedure with decisions that depend on new observations.

![Four compact diagrams compare a sequence, a candidate search, an iterative loop, and an acyclic dependency graph.](https://idylliclabs.com/images/elements-book/reasoning-02-v2.png)

A sequence fixes an order, candidate search compares alternatives, a loop responds to observations, and a dependency graph waits for required inputs.

## Required stages

Some steps need to happen on every run. If every draft must pass a citation check, code can require that stage. The model can still choose searches based on what it finds in the sources. Describing a check in a prompt may lead the model to perform it; putting the check in the program ensures it runs before the draft can be accepted.

For example, a process can have three required phases: gather evidence, draft, and review. Within the first phase, a model chooses searches and examines their results. Code controls when the process may advance to drafting. A failed review can return the draft for revision. The inner loop discovers a useful sequence of actions while the surrounding workflow preserves the required stages.

![Choose search, search, and observe lead to an enough-evidence decision. No returns to choosing a search; yes advances to draft and citation check. A failed citation check returns to draft.](https://idylliclabs.com/images/elements-book/reasoning-03-v2.png)

A search produces an observation. The workflow either seeks more evidence or advances to drafting, then checks the draft.

## Operations between model calls

Every return from a model call gives the runtime an opportunity to change how the process continues. After a search, code can retrieve related evidence, select the passages needed for the next decision, summarize older exchanges to make room, or choose a model for the next step. These operations determine what the next invocation can use. A continuing agent retains its task through reconstructed context, not through a model carrying private state from one call to the next.

The table below names six common operations that code can perform between calls. Each changes what the next call receives or how the work continues.

| Operation | Concrete mechanism |
| --- | --- |
| Inject | Await a search result and include its evidence in the next input. |
| Verify | Check citations and use the findings to choose the next step. |
| Focus | Select one claim and the passages needed to review it. |
| Branch | Select one path with a condition, or start several paths at once. |
| Merge | Collect the required branch results, preserve disagreements, and synthesize. |
| Loop | Generate another candidate with feedback until accepted or stopped. |

A short TypeScript sequence makes three of these operations visible. Search obtains information, selection constructs the writer's input, and validation produces a finding for the controller. The helpers stand for application code. The next control decision can accept the draft, revise it with the finding, or stop.

```typescript
const sources = await search(question)             // inject
const evidence = selectPassages(sources, question) // focus
const draft = await write({ question, evidence })
const check = verifyCitations(draft, evidence)     // verify

await record({ draft, evidence, check })
// The controller must now choose accept, revise, or stop.
```

![Search returns a release announcement and an unrelated office announcement. Selection keeps source-4, which says an August release is planned. A draft claims current availability with that citation; a check finds the claim unsupported, and the controller chooses to retrieve release evidence.](https://idylliclabs.com/images/elements-book/reasoning-04-v2.png)

Search, passage selection, drafting, and checking form one process. The citation finding gives the controller a concrete reason to revise or gather more evidence.

## Planning

An agent loop does not require a separate planning stage. Choosing the next action can include deciding what must be learned or accomplished first. An explicit plan becomes useful when the task has dependencies or unfinished work that later calls need to recover. The plan records an intended sequence; observations can change that sequence as the agent works.

For example, a plan to compare two released products rests on the assumption that both have shipped. If a search finds only an announcement for one, the next call may seek release evidence, explain the uncertainty in the comparison, or ask whether to narrow the task. A useful plan preserves what was intended alongside what was attempted and observed. Later calls can revise the remaining work instead of continuing as though the original assumption had been confirmed.

![A four-row trace changes a plan to compare released products after a source reveals that one is only announced.](https://idylliclabs.com/images/elements-book/reasoning-05.png)

A plan is useful when observations can change it. The runner must preserve what happened and reconsider the next step.

## Execution traces

A trace records the trajectory the system actually took: the input to each decision, the proposed action, the observed result, and whether the run continued or stopped. That record makes implicit choices inspectable after execution. Repeated searches may reveal that the model lacked a useful observation or failed to use one it had. A rejected edit may reveal stale document context. The repair depends on which part of the process failed.

Additional calls make sense when they add an observation, a different view of the problem, or a useful check. They also add latency and opportunities to lose information. A pipeline can guarantee that a stage runs, but cannot guarantee that the stage reaches a correct conclusion. The useful design question is what each additional step contributes toward the required result.

![An edit expecting revision 12 reaches storage containing revision 13. The version check reports a mismatch and rejects the write, leaving revision 13 unchanged. A follow-up arrow directs the agent to read revision 13 before making another edit.](https://idylliclabs.com/images/elements-book/reasoning-07-v2.png)

The trace establishes a stale write attempt: the request expected revision 12, storage held revision 13, and the rejected write left revision 13 intact. The next step is to read the current version.

The agent loop turns model decisions and tool results into a continuing attempt to solve a task. Composition lets us place that loop within larger procedures, add independent investigations, and combine their findings. Once several reasoning structures have distinct responsibilities, we need to decide what each receives, when each runs, and how their results fit together. Those are the concerns of coordination.

[Previous Agency](https://idylliclabs.com/projects/elements-book/agency)

[Next Coordination](https://idylliclabs.com/projects/elements-book/coordination)

[Idyllic Labs](https://idylliclabs.com/)

[Writing](https://idylliclabs.com/writing)

[Markdown](https://idylliclabs.com/projects/elements-book/reasoning/index.md)