Read Pi as a real Agent Harness

The small agent in the previous lesson can feel abstract until you see the same pattern in a working coding tool. I use Pi as the case study because its tools are explicit and the code is small enough to follow.

Pi is a terminal coding harness released under the MIT License, which allows people to read, use, and modify its source code under simple conditions. You do not need to install it for this lesson.

Start with the familiar tools

At the revision pinned by this Course, Pi exposes filesystem tools with the same jobs you have already learned:

• find discovers paths from glob patterns and respects ignored files;
• grep searches content with literal or regular-expression patterns;
• read returns a file or bounded line range.

The names differ slightly from BuildRAG, but the concepts are the same. Discovery narrows the search space. Content search locates possible Evidence. Bounded reads bring a useful section into model context.

flowchart LR
    M[Model] --> F[find]
    F --> M
    M --> G[grep]
    G --> M
    M --> R[read]
    R --> M
    M --> A[Answer or another tool]

Follow one tool call through the harness

The model does not execute grep itself. Pi sends the active tool definitions with the conversation. When the model requests a tool, the harness finds the matching implementation, validates the arguments, runs it, and appends the result to the next model turn.

That loop continues until the model returns ordinary text instead of another tool request.

Large tool outputs are truncated. This is not only a user-interface choice. Tool output becomes model input, so unbounded output can fill the context window and crowd out the Query and earlier Evidence.

What I want you to notice

The interesting part is not that Pi can search files. Your terminal already does that. The harness turns familiar operations into bounded model capabilities:

• the tool description tells the model what it may request;
• validation rejects malformed calls;
• the implementation controls filesystem access;
• truncation protects context;
• the session records what happened.

Those responsibilities stay with the harness even when the model is very capable.

The Course links to pinned upstream source so the explanation does not drift when Pi changes. Any quoted excerpt must keep the Pi copyright and MIT attribution. We do not copy the full harness into BuildRAG because the retrieval ideas are clearer when you map them to the smaller agent you already understand.

A model choosing tools introduces a new security boundary. Retrieved text can contain instructions, tool arguments can be unsafe, and a private Source can leak before generation begins. We will handle those cases next.

Secure retrieved content and tools