# How coding agents work: example scenario

One tiny task, creating and running hello world, traced turn by turn to show what the model sees, what it asks for and what the harness does.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/example-scenario

## Scenario

This scenario is deliberately not `ticket-service`: the task is too small to distract you. You open a coding agent in an empty folder and type one sentence:

> **Create a hello world app in Python and run it.**

It looks like one step. Underneath, it is **three turns of the agent loop**, and in each turn the **model** decides while the **harness** acts.

## Before → after

| | Before | After |
|---|---|---|
| Who acts | "The AI wrote and ran my code" | The model *asked*; the harness wrote and ran |
| Memory | The agent seems to remember things | The whole context is re-sent every turn |
| Failures | They feel random | You see which turn failed, and who was involved |

## Design

**Diagram:** Each turn the model reads the whole context and picks one step; the harness carries it out and feeds the result back.

- Turn 1 · write the file:
  - Model reads — instructions, tools, your request
  - →
  - Model asks — write hello.py
  - →
  - Harness does — checks permission, writes file
  - →
  - Fed back — "wrote hello.py"
- Turn 2 · run it:
  - Model reads — all of the above + result
  - →
  - Model asks — run python hello.py
  - →
  - Harness does — runs command, captures output
  - →
  - Fed back — "Hello, world!" · exit 0
- Turn 3 · answer:
  - Model reads — everything so far
  - →
  - Model answers — text, no tool call
  - →
  - Harness does — shows answer, ends loop
  - →
  - You see — "Created and ran it."

The model never touches your disk. It emits text, either an answer or a structured **tool call** like this one from turn 1 (simplified):

```json
{
  "tool": "write_file",
  "path": "hello.py",
  "content": "print(\"Hello, world!\")\n"
}
```

It is plain JSON: the name of one tool from the list the harness offered, plus its arguments. The harness reads it, writes the file itself and sends the result back to the model. (`\"` and `\n` are JSON's way of writing a quote and a line break inside a string.)

## What happens at runtime

The model has no memory between turns. The harness sends the **whole context window** again, a little longer each time:

**Diagram:** What the model reads on turn 3 (simplified); the harness assembles it, the model adds one step.

- Context window · turn 3:
  - System instructions, tool list — added by the harness
  - Instruction files — project conventions, if any
  - Your request — Create a hello world app in Python
  - Turn 1 · call + result — write hello.py → "wrote hello.py"
  - Turn 2 · call + result — run python hello.py → "Hello, world!"

If the machine only had `python3`, turn 2 would return `command not found · exit 127`. That result lands in the context, and on turn 3 the model asks for `python3 hello.py`. **Errors are feedback too.**

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| Model claims success without running anything | No tool result in the transcript, only the final sentence | Ask it to run and show the output |
| Huge command output | Slow, costly turns; the context fills up | Keep tool output short; filter or truncate it |
| Command runs with your full permissions | Files or network reached unexpectedly | Run inside a [sandbox](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing) |
| The check keeps failing and the model keeps retrying | The same error repeats across turns | Set explicit limits; see [loops](https://ai-sw-factory.mellicci.dev/fundamentals/loops) |

## Where the next concepts plug in

| Moment in the loop | Concept |
|---|---|
| The harness assembles the context | [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files), [skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills) |
| The model picks from the tool list | [MCP](https://ai-sw-factory.mellicci.dev/fundamentals/mcp) adds more tools |
| Just before and after a tool runs | [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) |
| A branch of work goes to a fresh context | [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents) |
| The whole setup is shared with a team | [Plugins](https://ai-sw-factory.mellicci.dev/fundamentals/plugins) |
| Nobody types the request | [Headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution) |
| The loop keeps going until a goal is met | [Loops](https://ai-sw-factory.mellicci.dev/fundamentals/loops) |
| Where the command actually runs | [Sandboxing](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing) |
| "Is this tool call allowed?" | [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) |