Frontend · Agent · Artificial Intelligence

Giving an LLM Its First Tool: How to Let an AI Agent Read Your Project Files

By 不一样的少年_ · Jul 20, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Tool calling is the mechanism that turns a chatbot into an agent. This walkthrough strips away frameworks to show the exact handshake: a JSON Schema tool definition, a single OpenAI API call with `tools`, and a program-side switch that executes the requested function. Understanding that loop is prerequisite to building agents that read, write, and run commands autonomously.

Summary

A terminal-based AI agent built from scratch in TypeScript moves beyond blind Q&A. The agent now carries a `read_file` tool, described via JSON Schema, that lets it request file contents when it needs context it doesn't have. A Node.js backend catches the tool-call request, reads the real file from disk, and feeds the content back to the model for a grounded answer. The implementation deliberately limits reads to the project directory and caps file size at 8,000 bytes to control token costs and prevent directory traversal. The core loop — AI requests a tool, the program executes it, the result goes back to the model — is the foundation for multi-step agent behavior that will be expanded in later installments.

Takeaways

— An LLM cannot read files directly; it can only emit a structured request that a host program must fulfill.

— Defining a tool for OpenAI means providing a JSON Schema object with a name, description, and typed parameters.

— Passing `tools: [READ_FILE_TOOL]` in a chat completion request tells the model it may request that function.

— The model's response includes a `tool_calls` array; the program inspects it, executes the corresponding function, and sends the result back in a follow-up message with role `tool`.

— Directory traversal is prevented by resolving the requested path against the working directory and rejecting any path that escapes it.

— File reads are capped at 8,000 bytes to avoid blowing up token usage on large files.

— The current implementation handles exactly one tool call per turn; a multi-step agent loop is the next logical extension.

Conclusions

Frameworks like LangChain abstract this exact loop, but the underlying mechanism is only two API calls and a function dispatch — simple enough to build and debug directly.

Restricting file access to the project root and capping read size are not afterthoughts; they are essential safety and cost controls that must be designed in from the start.

The single-turn limitation is deliberate pedagogy: mastering one request-execute-return cycle makes the jump to a multi-turn agent loop a small, understandable step rather than a leap.

Concepts & terms

Tool calling (function calling)

An LLM API feature where the model, instead of returning text, returns a structured JSON object requesting that a specific function be executed with given arguments. The caller runs the function and sends the result back to the model.

JSON Schema for tools

A JSON object that describes a callable function to an LLM, specifying the function name, a natural-language description, and the expected parameters with their types and whether they are required.

Agent loop

A control flow where an LLM repeatedly decides whether to call a tool or return a final answer. Each tool result is fed back into the model, which can then request another tool or respond to the user.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗