Agent Design in Practice: AI Agent and Tool Design Principles from an Auto Bug-Fixing Project

GitHub Copilot's paid feature can automatically generate PRs from issues. This capability sounds impressive, but how is it implemented? A Bilibili creator (EchoDM) recreated this feature to explore the design philosophy behind AI Agents. This project is not just a technical demo but also a record of thinking on how to build a practical Agent system.

Project Overview: A Plugin-Based Auto Bug-Fixing Bot

The essence of this project is a GitHub plugin: once installed on any repository, users only need to submit an issue, and the plugin will automatically analyze the requirements, modify the code, run tests, and finally create a PR. The creator demonstrated five issues; the first four were about implementing different sorting algorithms, and the last one was about transforming the project into a command-line tool. Each issue successfully triggered automatic PR generation, and the PRs included detailed execution information.

The entire process runs on GitHub Actions. The script divides the Action into four steps:

1. Authorization and Task Parsing: Confirm that the user submitting the issue has permission, and extract a clear "task" from the issue description.
2. Working Branch Preparation: Check whether there is already a corresponding PR for the issue, and decide whether to create a new branch or continue modifying the existing PR.
3. Agent Modification and Verification: The Agent calls tools to modify the code according to the task, and runs tests via Docker to verify whether the modifications meet the requirements.
4. Publish PR: Create a PR for the repository maintainer to review.

This architecture clearly decouples "task understanding," "environment preparation," "code modification," "verification feedback," and "result delivery," reflecting a key principle in Agent system design: let the model focus on decisions while handing deterministic operations to code.

GitHub Actions is a continuous integration and continuous deployment (CI/CD) service provided by GitHub, allowing developers to define automated workflows in repositories. Each workflow is triggered by events (such as issue creation or code push) and runs on virtual machines or containers provided by GitHub. In this project, GitHub Actions serves as the Agent's runtime environment: when a user submits an issue, the Action starts automatically and executes predefined script steps. Since Actions natively support Docker containers, the project can conveniently use Docker to ensure consistency of the test environment, thereby reliably verifying code modifications. This design decouples the Agent's decision logic from the execution environment, making the system easier to maintain and extend.

The Agent's Core Loop: Input, Invocation, Feedback

The Agent's operating mechanism can be summarized as a simple loop: the model receives the task description, calls tools to perform operations, takes the results returned by the tools as new input, makes decisions again, and repeats until the model considers the task complete.

This loop may seem basic, but it contains the essence of Agent design: tools are the bridge between the model and the external world. The model does not need to know all the details of the codebase; it only needs to obtain sufficient context through tools and then decide the next step. This design keeps the system flexible and extensible.

The creator designed three types of tools in the project:

• Code search tools: help the model locate the code that needs to be modified.
• Code modification tools: perform specific code changes.
• Code verification tools: run tests to check whether the modifications pass.

These three types of tools exactly correspond to the closed loop of "perception—action—verification," forming the minimal toolset for the Agent to complete code modification tasks.

In the context of Agents, "tools" refer to external functions or interfaces that the model can call to perform specific operations (such as searching code, modifying files, or running tests). The model itself does not directly operate the file system or network; instead, it requests tool execution by generating specific invocation instructions and uses the returned results as input for the next decision. This design is based on the reasoning capabilities of large language models: the model decides when to call which tool and what parameters to pass based on the task description and the context returned by tools. Tool calls are usually represented in a structured format (such as JSON) for easy program parsing and execution. By combining multiple tools, an Agent can complete complex multi-step tasks without hardcoding all logic inside the model.

Agent Design Principle One: Simplicity Above All

The creator repeatedly emphasized that the most important principle in designing Agent systems is simplicity. Agent frameworks are emerging one after another today, but in many scenarios there is no need to introduce complex frameworks. Instead, directly wrapping one or two layers of abstraction around AI-native APIs is more controllable and easier to debug.

He decomposed the Agent system into three parts: the user, the model, and hardcoded rules (Harness). The model is like "changeable water," while hardcoded rules are the "pipes" that define the direction in which the water flows. Designing an Agent system means setting appropriate rules for these three according to the goals, scenarios, and business conditions.

In this project, the core of the rules is division of responsibilities: the user is responsible for proposing requirements (issues), the model is responsible for decisions and tool calls, and the hardcoded Action script is responsible for deterministic tasks such as permission validation, branch management, and Docker verification. This division frees the model from trivial environment operations so that it can focus more on code modification itself.

This "simplicity" philosophy is also reflected in debugging convenience. The creator recommends customizing the output format of key data so that problems can be quickly located when the Agent behaves abnormally. Compared with relying on the black-box behavior of frameworks, controlling the data flow yourself is clearly more reliable.

Harness (the hardcoded rule layer) refers to the deterministic control logic built around the model, responsible for handling aspects that the model is not good at or should not handle, such as permission validation, error handling, resource management, and state maintenance. In an Agent system, the Harness defines what the model can do, what it cannot do, and how it interacts with the external environment. It is usually implemented in traditional code to ensure the system's safety and reliability. For example, in this project, the Harness includes steps such as checking user permissions, creating branches, and running Docker tests. By handing deterministic operations to the Harness, the model can focus on tasks that require reasoning and decision-making, thereby reducing the complexity and uncertainty of the overall system.

Agent Tool Design Principle Two: Design for the Model

The quality of tool design directly determines the success or failure of an Agent. The creator pointed out that the design of Agent tools is completely different from ordinary API design and needs to be considered around "how the model calls them."

He summarized six tool design principles:

1. Start from the task: The toolset should be built around the tasks the Agent needs to complete, rather than blindly piling up features.
2. Clear naming and single responsibility: Tool names should directly reflect their purpose so that the model can easily understand when to call them.
3. Transparent parameters and return values: Use straightforward variable names, clearly explain purposes and return values, and preferably provide examples.
4. Return meaningful context: The content returned by tools should be information useful for the model's decision-making, not a pile of raw data.
5. Return only necessary information: Avoid information overload and give the model only exactly what it needs.
6. Continuously iterate and optimize: Put tools into real tasks, observe their performance, and continuously adjust based on feedback.

The core idea of these principles is: reduce the cognitive burden on the model when calling tools. The model is not a human developer; it cannot understand tools by reading documentation and can only infer from names, parameters, and return values. Therefore, tool design must be "self-explanatory," allowing the model to use them correctly after only a few attempts.

The creator also mentioned that the tool iteration process can be run by the Agent itself without much manual intervention. By observing the Agent's performance in real tasks, developers can quickly identify flaws in tool design and improve them.

Summary and Insights

Although this auto bug-fixing project is small in scale, it fully demonstrates the key design decisions of an Agent system. It tells us that building a practical Agent does not require a complex framework; instead, it requires clear division of responsibilities, simple abstraction layers, and a toolset tailored for the model.

For developers who want to try Agent development, this project provides a reusable approach: start from specific tasks, design a minimal toolset, keep the system simple and debuggable, and let the model make autonomous decisions in the loop. As the creator said, the model is water and the rules are pipes—good design is about letting the water flow smoothly through the right pipes.

(Project source code and accompanying learning documents can be obtained from the creator's repository.)