Assistant interaction modes

What you will be able to do

Know what a coding assistant can see, change and run before you ask it for anything. Chat, completion and agents help in different ways, and each way leaves different work for you to check.

Before you startWhat to know and to have readyAbout 40 minutes

What you need to know

• The ticket-cleaner project: it checks Larkfield’s support tickets and writes reports/summary.json. You built it in Python for Practical AI Engineering.
• How to read a diff: - marks a removed line, + marks an added line, and @@ gives the line numbers. Track a first change in Git and Team Development Essentials explains it.

What you need on your computer

• Nothing for this lesson. You read two recorded sessions, in the browser or in the labs folder C15/transcripts/. You set up the project in the next lesson.
• You do not need a coding assistant, an account or money for this course. If you have an assistant, you can use it for the same tasks.

Three ways to get help with a letter

Think of three ways to get help with an important letter.

You can read a paragraph to a friend on the phone. She suggests a better sentence, and you type it into your letter yourself. She knows only what you read to her.

You can type the letter on your phone, where the keyboard suggests the next word. It sees only the sentence that you are writing, and a word goes in only when you tap it.

Or you can give a friend your laptop and say: “Fix my letter.” She opens the file, changes many sentences, and perhaps also sends an email for you. This is the fastest way. But afterwards, you must read the whole letter again, and you must know what else she did on your laptop.

The three helpers can be equally clever. What is different is what they can see and what they can touch. Coding assistants come in the same three kinds.

Larkfield’s next task

You know Larkfield’s help desk from the Python and Git courses. Grace, the support lead, uses the weekly report of ticket-cleaner. She has sent Amira two emails. In the first, she asks for the report of one category, or two:

The billing team only needs billing, and the shipping team only needs shipping. Can I ask the report for just one category, or two when a lead has two teams?

In the second, she reports a bug: the report of the new web form’s export has three login lines instead of one. Both emails are in the labs folder C15/emails/.

Amira, a developer, will do both tasks with a coding assistant in this course. Kwame, the solution architect, will review what the assistant can touch. Tomás, an AI engineer, likes fast shortcuts, and he will propose a few. The course has real recorded sessions of an assistant for every step, so you can follow without one.

What a coding assistant is

A coding assistant is a program that sends your request, and some of your code, to a language model. Then it turns the model’s answer into a suggestion or a change. A language model is a program that learned from a very large amount of text. Given some text, it predicts the text that is likely to come next.

This one fact explains most of this course. The model writes what looks likely. It does not check that a function exists, that a package is real, or that a number is right. Often the likely text is also correct. Sometimes it is not, and then it looks exactly as confident.

A tiny example: a diff that only looks right

The course team gave Grace’s feature to a model in a chat, with the five files that it needed. The model answered with a diff. One block of the diff, a hunk, starts with this line:

@@ -21,10 +21,23 @@ def average_priority(tickets: list[Ticket]) -> float | None:

The header promises that the hunk covers 10 lines of the old report.py and 23 lines of the new one. Count the lines that follow it in the reply:

Kind of line	Starts with	Count
Lines that stay	a space	8
Lines removed	-	2
Lines added	+	14
Old version: stay + removed		8 + 2 = 10
New version: stay + added		8 + 14 = 22, not 23

The model wrote a number that looks right for a header, but the number does not match the lines that it wrote. So when the course team applied the reply with git apply, Git read 22 lines and looked for one more. It found the next header instead:

error: corrupt patch at reply.diff:54

No file changed. The code in the reply may be good, but nobody could use the reply as it was.

Three modes, and what each one can touch

Assistants differ in what they can see, what they can change and what they can run. This course calls these three kinds modes.

• Chat. You paste code and a question into a chat window, in a browser or in your editor. The assistant answers with text. It sees only what you pasted, and it changes nothing. You copy its answer into your files.
• Completion. While you type in your editor, the assistant suggests the next few lines in grey. It sees the file that you are typing in, and often other open files. A suggestion goes into the file only when you accept it, usually with the Tab key.
• Agent. The assistant works in your project folder. It reads the files that you give it, and a map of the repository. It changes the files itself, often many files in one step. If you allow it, it also runs commands in your terminal, such as the tests or pip install.

The repository context is the part of your project that an assistant gets with your request. It can be files, a list of the other files, error messages and examples. Module 2 shows how to choose them.

Three modes of coding assistant. From chat to agent, the assistant sees more and touches more, so you have more to check.

Text description of the diagram

The diagram has three columns. The chat window sees only what you paste into the message. It changes nothing, because it answers with text that you copy into your files, and it runs nothing. You move the code. Completion in the editor sees the file that you type in, and often other open files. It changes a few lines at your cursor, only when you accept them, and it runs nothing. You accept each suggestion. The agent sees the files that you add and a map of the repository, and it can ask for more. It changes the files in your project, many files in one step, and it runs commands in your terminal if you allow it. The assistant moves the code. An arrow under the three columns, from chat to agent, says: the more it can see and touch, the more you must check.

One tool can offer all three modes, and you choose one for each task.

The same task in chat and in an agent

The course team gave the same task, Grace’s --category option, to the same model in two modes. The task was a written brief with seven criteria that a test can check; Module 2 shows how to write it. After each session, a script ran the tests, ruff and eight hidden checks, one for each criterion (criterion 4 has two). The prompt is the text that you give the assistant: your request, with any files or examples. Every session of this course has a transcript: a record of the exact prompt, everything that the assistant printed, the diff and the test results.

Chat mode (transcript feature-chat-mode). A short script sent the brief and five files in one message, as you do when you paste them into a chat window. The reply started like this:

What the assistant printed (start)

Adds repeatable, case-insensitive category filtering while preserving whole-file totals and the existing report when no category is supplied. Includes documentation and regression tests for criteria 1–6 and help text.

I can’t run pytest, Ruff, or the sample commands in this chat environment.

Then came the diff for five files. It did not apply, as you saw above. In chat mode, moving the code into your files is your job, and here that job failed.

Agent mode (transcript feature-bounded). Aider, an open-source assistant that works in a terminal, got the same brief and the same five files. It printed its own setup first:

What the assistant printed (start)

Aider v0.86.2
Model: openai/chat-strong with diff edit format
Git repo: .git with 24 files
Repo-map: using 4096 tokens, auto refresh
Added README.md to the chat.
Added tests/test_cli.py to the chat.
Added tests/test_report.py to the chat.
Added ticket_cleaner/cli.py to the chat.
Added ticket_cleaner/report.py to the chat.

At the end, it changed the files itself:

What the assistant printed (end)

Applied edit to ticket_cleaner/cli.py
Applied edit to tests/test_cli.py
Applied edit to ticket_cleaner/report.py
Applied edit to tests/test_report.py
Applied edit to README.md

The result: 5 files changed, with 145 lines added and 4 removed. The tests passed (35 passed), and all 8 hidden checks passed. But ruff format --check failed with 2 files would be reformatted, because some new lines were too long. Even the change that worked was not ready to accept.

What each mode sent to the model

Why could the agent do more? Because it sent more. A token is the unit in which a model counts text: a short word, or a part of a longer word. The chart compares the tokens that went to the model (in) and came back (out).

• Tokens sent to the model
• Tokens in the reply

The same task in two modes, one model call each. The agent sent about twice as much text, because it added its own instructions and a map of the repository.

Text description of the chart

A column chart with four columns. The chat mode sent 2,688 tokens and received 2,554. The agent sent 5,527 tokens and received 2,061. The agent sent about twice as much, and the two replies have a similar size.

The request logs show what was in each message, measured in characters:

Part of the request	Chat	Agent
The tool’s own instructions, with examples	296	5,244
A map of the repository	none	2,261
The five files	10,657 (files and task together)	10,083
The task		4,067

The repository map lists the files that Git tracks, with the names of their functions. It tells the agent that parsing.py has a clean_category() function, without sending the whole file. Here is the start of the map, exactly as the model received it:

Part of the agent's request: the repository map

Here are summaries of some files present in my git repository.
Do not propose changes to these files, treat them as *read-only*.
If you need to edit any of these files, ask me to *add them to the chat* first.

.env.example

.gitignore

data/tickets-excel.csv

So an agent tells the model about files that you never mentioned. That is useful. It is also why the next two lessons matter: the agent sees what your repository contains.

An agent checks its own edits, and it still makes mistakes

The same brief also ran with a smaller, cheaper model (transcript feature-bounded-small). Its first answer tried to change a line of README.md that does not exist. It quoted the options table with an extra (default: reports/summary.json), a line that looks likely. Aider could not find that line, so it sent the error back to the model:

What the assistant printed

# 1 SEARCH/REPLACE block failed to match!

## SearchReplaceNoExactMatch: This SEARCH block failed to exactly match lines in README.md

The model answered again with the real line, and Aider applied it. In chat mode, the same kind of mistake would reach you. The agent caught it, but only because the mistake made an edit impossible. A wrong line that fits the file goes in without a warning.

Completion: small steps that you accept

The course did not record a completion session, because suggestions appear while you type and are hard to record honestly. The course team wrote this short example for the lesson, to show what a completion looks like. In report.py, Amira types the first line of a new function. Grey text appears after her cursor:

def count_by_status(tickets: list[Ticket]) -> dict[str, int]:
    """Return the number of tickets for each status."""        # grey: suggested
    return dict(Counter(ticket.status for ticket in tickets))  # grey: suggested

If she presses Tab, the two grey lines go into the file. Counter is not imported in report.py, so the function fails when it runs, until she adds the import. A completion is small, so a mistake like this is easy to see. But many small suggestions, accepted quickly, add up to a lot of code that nobody read slowly.

Which mode to use, and what it costs

Tomás has read the two transcripts. “The agent did everything in one step. Let’s always use agents.” Kwame asks him one question: “What else can it touch while it works?”

Each mode fits a different job:

• Chat fits questions and explanations, such as “What does this error mean?” or “Explain this function.” It touches nothing, so it is the safest mode. For a change to several files, moving the code by hand is slow and easy to get wrong, as the corrupt patch showed.
• Completion fits small, local code that you are writing anyway: a loop, a test case, a docstring. You stay in control of each line. It sees little of the project, so it cannot know your rules.
• An agent fits a change across several files, with tests to run. It saves the most typing. It also needs the most preparation: a clean starting point, written limits, and a full review of its diff. This module and Module 3 teach them.

What does a session cost? Learners who use a free tier, or no assistant, pay nothing. The course team paid for the recorded sessions, at the prices of the course’s model deployments. For the larger model, that is US$2 per million tokens sent and US$10 per million received. Prices change: check the current price list of your provider. The chart shows five of the recorded sessions:

• Larger model
• Smaller model

The cost of five recorded sessions, in US cents. One question to the smaller model cost 0.05 cents; a plan and one step with the larger model cost 5.03 cents.

Text description of the chart

A column chart with five columns, in US cents per session. One question to the smaller model (“ask”): 0.05. Grace’s feature with the smaller model (“small”): 0.28. The feature in chat mode with the larger model (“chat”): 3.09. The feature with the agent and the larger model (“agent”): 3.17. A plan first, then one step, in three model calls (“plan”): 5.03.

All 17 recorded sessions together cost US$0.3965. One session took from 2.3 to 35.7 seconds of model time. The money is small. The real cost is your time to check the result.

Common mistake

A diff from a chat does not apply

Symptom: you save the diff from a chat reply as a file and run git apply reply.diff. Git prints error: corrupt patch at reply.diff:54, and no file changes.

Cause: the model wrote the diff as text, line by line. A wrong number in a header, a missing space at the start of a line, or a shortened line breaks the format. The code inside can still be right.

Fix: do not change numbers until Git accepts the file. Ask for the whole new function instead of a diff, and put it in by hand. Or use a mode that edits the files itself. In both cases, read git diff afterwards: Git makes that diff, so you can trust its format.

Guided practice: compare two recorded sessions

1. Open the labs folder C15/transcripts/ on GitHub, or in your clone of nextia-learning-labs.
2. Open feature-chat-mode.md. Read the table at the top, then the prompt.
3. Find the line that starts with Applying the reply's diff:. Write down what happened.
4. If you cloned nextia-learning-labs, go to the clone’s folder and run git apply --check C15/transcripts/feature-chat-mode.reply.diff. This file is the reply’s diff, unchanged. With --check, Git only tests the diff and changes no file. Compare the error with the line from step 3.
5. Open feature-bounded.md. Read the same table and the same prompt.
6. Find the line that starts with **After turn 1:**. Write down the number of files and lines.
7. Find the line that starts with Checks:. Write down the test result and the result of ruff format --check.
8. Fill in this table for both sessions: mode, files given, who changed the files, files changed, tests, hidden checks.

Show the answer

	Chat (feature-chat-mode)	Agent (feature-bounded)
Mode	chat: one message, the reply’s diff applied with git apply	agent: Aider edits the files
Files given	five: cli.py, report.py, README.md, test_report.py, test_cli.py	the same five, and the repository map
Who changed the files	nobody: git apply failed (corrupt patch)	the assistant: Applied edit to … five times
Files changed	0	5, +145 −4
Tests	24 passed (the old tests only)	35 passed
Hidden checks	1 of 8: only “the report is the same without the option”, which was true before	8 of 8
ruff format	pass: nothing changed	fails: 2 files would be reformatted

In step 4, Git prints error: corrupt patch at C15/transcripts/feature-chat-mode.reply.diff:54: the same line 54 as in the recording.

The agent’s session was more useful, but it still left work: 145 lines to read and two files to format.

Your turn: the smaller model

Open feature-bounded-small.md. Before you read the end, predict: will the smaller model’s change be larger or smaller than the larger model’s? Then answer three questions. How many model calls did the session make, and why more than one? How many files and lines changed? Did ruff format --check pass?

Show the answer

The session made 2 calls. The first answer had one edit that did not match README.md, so Aider sent the error back, and the second call fixed it. The change was smaller: 5 files, +86 −3, against +145 −4. The tests passed (30 passed), all 8 hidden checks passed, and ruff format --check passed. It cost US$0.0028, about one tenth of the larger model’s session. A smaller model is not always worse. And a different run of the same prompt can give a different answer. The course team ran the larger model’s prompt twice, and got +129 −5 and +145 −4.

Knowledge check

Check your understanding

For each mode (chat, completion, agent), say what the assistant can see, what it can change and what it can run.

Show the answer

• Chat: it sees only what you paste. It changes nothing: you copy its answer into your files. It runs nothing.
• Completion: it sees the file that you type in, and often other open files. It changes a few lines at your cursor, only when you accept them. It runs nothing.
• Agent: it sees the files that you add and a map of the repository, and it can ask for more. It changes files in your project itself, often many in one step. It runs commands in your terminal if you allow it.

Check your understanding

A model wrote a hunk header that promised 23 new lines, and the hunk had 22. Explain how this can happen, with what a language model does.

Show the answer

A language model predicts the text that is likely to come next. A header such as @@ -21,10 +21,23 @@ is likely text at that place, so the model wrote one. It did not count the lines that it wrote after it. The same reason explains invented function names, invented packages and wrong numbers: they look likely, and nothing in the model checks them. So you check them, with Git, the tests and your own reading.

Check your understanding

Tomás says: 'The agent applied its edits and the tests pass. That means the change is ready.' Use the feature-bounded session to answer him.

Show the answer

Applied edits and passing tests are not enough. In feature-bounded, all 35 tests passed, but ruff format --check failed on 2 files. The agent also changed 5 files with 145 new lines, which somebody must read before the team accepts them. The tests check only what they test: the next lesson shows a change whose own tests pass while it changes every report. The more an assistant can touch, the more you must check.

Case studies in this course

At the end of the course, you use what you learn on a realistic project, from the data to the recommendation. Complete at least one for the certificate; the others are optional.

• Fix a bug in an unfamiliar codebaseMap a small Python project that you have never seen, reproduce a customer's bug, write the failing test, fix it with an assistant's help, and compare your fix with the maintainers' fix.
• Upgrade a dependency safelyMove a small project across a real breaking change of a dependency, and check each suggested change against the changelog and the tests.

Recap

• A coding assistant sends your request and some of your code to a language model, which predicts likely text. Likely is not checked: a hunk header promised 23 lines and the hunk had 22, so git apply failed.
• Chat sees what you paste and changes nothing. Completion suggests a few lines where you type. An agent reads files and a repository map, changes many files itself, and can run commands.
• On the same task, the chat reply’s diff did not apply. The agent changed 5 files (+145 −4), and every check passed except the format check.
• The agent sent about twice as many tokens, because it adds its instructions and a repository map. The recorded sessions cost from 0.05 to 5.03 US cents; the larger cost is your time to review.

Next, you prepare the project, so that every change of an assistant shows as a clean diff, next to checks that passed before.

Next: Repository preparation