How does Agent Engineering work? I'll make it clear with a real link

This link starts with the Notion requirement

The real scenario is this: you are developing a microservice and need to add an alarm module to the existing code base. Tasks are written on Notion, and you need Agent to help you complete the entire process from requirement analysis to code submission.

The first step is not to write code, but to define the tool. You need to tell the Agent: how to obtain Notion documents, search tools for the code base, execution permissions for terminal commands, and Git operation interfaces. Each tool is an API call declaration - including parameters, return values ​​and failure handling. This is the most basic and easily overlooked link in Agent Engineering: Tool Definition.

If the tool definition is incomplete, the Agent will get stuck at the first level. For example, if only the Notion API is given but no authentication token is given, the Agent will try three times and then exit with an error. Many teams attribute this failure to "AI lack of capabilities." In fact, the tool layer is not solid.

Core loop: planning, calling, observing, adjusting

After the tool is ready, the Agent begins its core loop. Take the alarm module task just now as an example:

1. Planning: Agent reads Notion requirements, calls the code search tool to find the current project structure, and then generates an execution plan - create new files, modify configuration files, and add dependencies.
2. Call tool: It first executes git pull to get the latest code, and then creates a new file. The key here is that the Agent generates specific commands and the system forwards them to the terminal for execution.
3. Observation results: If the file is created successfully, the terminal returns the path and permission information; if it fails (for example, the directory does not exist), an error code is returned. The agent needs to adjust its next steps based on the observations.
4. Adjustment: Agent will re-plan when it fails, for example, create a directory first and then create a file. This process may be iterated several times.

This cycle seems simple, but the failure is hidden in the details. The most typical mistake is: the agent is overconfident after the first tool call is successful, skipping verification and going directly to the next step. For example, after creating the file, you did not check whether the content was correct, and directly performed code formatting, resulting in an empty file being formatted.

Context and MCP: Don’t let the Agent get lost

With loops, the agent also needs to remember what it is doing. This is Context Management.

The input and output of each tool call are written to the context window. The problem is, the context window has an upper limit - 128K tokens for GPT-4 and 200K tokens for Claude. When the loop is executed more than 10 times, the context may be filled with history logs. At this point the Agent begins to "forget": it may forget the original requirement, or repeat operations that have already been completed.

The solution is MCP (Model Context Protocol). This is essentially a context pruning strategy: only keep system prompts, tool results, and summaries relevant to the current step, and discard irrelevant details. During implementation, context quality can be controlled through sliding windows, importance scoring, etc.

For example, in my practice, each cycle only retains the results of the last 5 tool calls, and the results beyond that are compressed into a one-sentence summary. This allows the Agent to maintain over 90% accuracy in complex tasks exceeding 30 steps.

Permission model: the most easily overlooked pitfall

The biggest difference between Agent Engineering and ordinary programming is: What you grant to the Agent is the operation permission, not the code logic.

You need to answer three questions:

• What file system paths can the Agent access?
• What terminal commands can the Agent execute (e.g. rm -rf should be disabled)?
• What external APIs can the Agent call (for example, the production environment database must be read-only)?

The failure scenario is very specific: a team allowed the Agent to directly execute npm publish, and as a result, it published the unfinished package to the npm official repository during the debugging process. This type of problem cannot be solved through prompt engineering and must be controlled from the tool permission level.

My approach is to bind a security ID to each command in the tool definition, and verify permissions before executing on the terminal. For example, file writing is only allowed in the /src and /tests directories, and the command blacklist includes rm -rf, sudo, publish, etc.

Failure recovery: do not interrupt workflow

Even with tool definitions, loops, context, and permissions, the Agent still fails. The question is: What to do if ** fails? **

Most implementations throw an exception and then stop. But real development scenarios require more: perhaps manual intervention and correction, and then letting the Agent continue from the breakpoint.

One possible design is the "checkpoint mode": every time a subtask is completed (such as file creation, test passing), the current state is saved to disk. When the Agent fails in subsequent steps, you can manually restore to this checkpoint, correct the problem, and restart the subsequent process.

The other is "explicit authorization mode": when the Agent encounters an error that cannot be resolved automatically (such as API authentication expiration), it should pause and request human input instead of blindly retrying.

For example, there is a "manual intervention gate" in my workflow: if the Agent fails to perform the same operation twice in a row, the system will pop up a terminal prompt asking the developer to enter new credentials or modify the path. After the developer enters the input in the terminal, the Agent continues execution.

When should we give up Agent?

The applicable boundaries of Agent Engineering are not infinite. There are several situations where hand coding or traditional automation is more appropriate:

• Highly security-sensitive operations: such as modifying the production environment configuration and operating real orders of financial data.
• Decisions requiring human judgment: such as interface design, naming conflict resolution.
• Non-deterministic tasks: Agent is not suitable for workflows that contain randomness (such as automatically generated passwords) or require multiple rounds of manual approval.
• Ultra-long cycle tasks: A single task exceeds 1 hour or 200 steps, and it is difficult for current context management technology to maintain consistency.

Outside these boundaries, Agent Engineering is significantly less effective. For example, when doing code refactoring, the Agent may introduce bugs because it cannot understand the implicit dependencies of the entire project. At this point, you should fall back to the traditional approach: manual refactoring + unit testing.

An executable checklist

If you are going to use Agent Engineering in a real project, here is a list I refined after practice:

1. Tool definition integrity check: Are the input/output/error codes of each tool declared?
2. Minimized permissions: Agent can only access files and commands it really needs.
3. Context pruning strategy: Set the maximum number of retention rounds (5-10 rounds recommended), and compress after exceeding.
4. Failure recovery mechanism: checkpoint + manual intervention interface.
5. Monitoring log: Record every tool call and decision to facilitate backtracking.
6. Test Sandbox: Run in an isolated environment first, confirm everything is correct, and then release permissions.

This list is not a one-time configuration and is completed, but must be reviewed before each task. I have seen too many cases where the permission check was skipped because "it was fine last week", and as a result, the Agent deleted the database this week.

Next step: Become an Agent Engineer

If you want to transform from an ordinary developer to an Agent engineer, the next step in this article should be a more systematic original paid article or course. In the course you will learn how to design tool invocation protocols, how to debug the Agent's context window, and how to build a production-level failure recovery system.