AI サービスが一時的に利用できないため、復旧後に翻訳を補完します。
What is Agent Harness Engineering? Build an Agent Loop in Python India's Most Futuristic AI Conference Is Back – Bigger, Sharper, Bolder d : h : m : s Career GenAI Prompt Engg ChatGPT LLM Langchain RAG AI Agents Machine Learning Deep Learning GenAI Tools LLMOps Python NLP SQL AIML Projects Reading list How to Become a Data Analyst in 2025: A Complete RoadMap A Comprehensive Learning Path to Tableau in 2025 A Comprehensive NLP Learning Path 2025 Learning Path to Become a Data Scientist in 2025 Step-by-Step Roadmap to Become a Data Engineer in 2025 A Comprehensive MLOps Learning Path: 2025 Edition Roadmap to Become an AI Engineer in 2025 A Comprehensive Learning Path to Master Computer Vision in 2025 Best Roadmap to Learn Generative AI in 2025 GenAI Roadmap for Enterprises Large Language Models Demystified: A Beginner’s Roadmap Learning Path to Become a Prompt Engineering Specialist A Practical Guide to Harness Engineering: Building the System Around the Model Janvi Kumari Last Updated : 19 Oct, 2026 16 min read An AI coding agent can write a function in seconds. But a working feature takes more than generated code. The agent needs to understand the project, find the right files, use tools safely, and check whether its changes work. A model on its own does none of that. It sees only the text it is given, and it cannot run a test or save its progress. The system that supplies those things is called a harness, and the work of designing it is called harness engineering. In this guide, we will look at what a harness is, how its parts fit together, and how it differs from prompt and context engineering. Then we will build a small harness in Python, with a sandbox, read-only tests, a step limit, saved progress, and a final check, and watch it handle a messy agent run. Table of contents Why a Model Alone Is Not Enough What Is Agent Harness? Prompt, Context, and Harness Engineering The Agent Loop The Six Layers of a Harness Security and Cost Limits Our Mini Harness: Architecture Hands-on Implementation of a Mini Harness How to Improve a Harness Harnesses Age, and What They Do Not Guarantee Conclusion Frequently Asked Questions Why a Model Alone Is Not Enough A language model generates responses from the information it receives. That simple fact leads to several limits when you ask it to do real work: It does not know which files are in your project unless you show them. It cannot run tests, call a database, or open a browser by itself. It does not remember what happened in an earlier session. It can say the work is done when it is not. It can take actions you did not intend if nothing limits it. It can only hold so much text at once, so too much context hurts. A harness is how we address these limits, one by one. What Is Agent Harness? An agent harness connects the model to information and tools, manages the steps of a task, and checks the result. Depending on the system, it may include: Instructions and project rules Context retrieval and memory Tools such as a terminal, browser, or database A controlled environment where actions run Workflow steps, approvals, and retries Tests, evaluations, and logs The model proposes what to do. The harness provides the information and capabilities needed to do it, and checks what happened. You can already see harnesses in everyday tools. Coding agents such as Claude Code and OpenAI Codex are a model plus a harness: file access, a terminal, project instruction files, permission prompts, and test runs. Two products can use the same model and behave very differently because their harnesses differ. The term is still new. People use “harness” a little differently, sometimes meaning only the tool-running code and sometimes the whole system around the model. This guide uses the broader meaning. Prompt, Context, and Harness Engineering These terms describe related parts of building AI systems. Here is how they compare: Aspect Prompt Engineering Context Engineering Harness Engineering Focus The wording of the instructions What information the model sees The whole system around the model Key Question How should I ask? What does the model need to know? What must it see, do, and verify? Example “Review this function and explain any security risks.” The function, related files, coding standards, test failures, and documentation A way to run tests and report results, linters that enforce architecture, and saved progress What It Controls The instructions The information supplied Context, tools, permissions, workflow, state, and checks Limit Can ask for tests but cannot run them on its own Can supply facts but cannot act or verify on its own Cannot guarantee every result is correct A prompt can tell an agent to run the tests. The harness must give it a way to run them and report whether they passed. A prompt can say “follow our architecture.” The harness can make the architecture easy to find and enforce important boundaries with tests or linters. These areas overlap, and a practical distinction is that harness engineering includes the runtime and controls around the model. The Agent Loop The harness does not call the model once. It runs a loop: build the context, let the model propose an action, run the action and check the result, then repeat. The loop ends when the checks pass. It also ends when a limit is reached, such as a step cap, and the agent reports where it stopped or asks a person for help. The harness rebuilds the context on every pass, so the model always sees the latest results. The model can say it is finished, but the harness decides whether the checks actually pass. The Six Layers of a Harness The exact design depends on the application, but most harnesses need six layers. Security and cost cut across all of them and get their own section after this one. 1. Instructions: make the rules clear Instructions give an agent a starting point. In a code repository, a short AGENTS.md or CLAUDE.md file can explain how to navigate the project, where to find deeper documentation, and which checks to run. Keep this entry point focused, and link to maintained documents for architecture, testing, security, and product behavior. Practical takeaway: Treat the main instruction file as a map to reliable project knowledge, not as a complete manual. 2. Context: provide the right information More context is not always better. Loading too many unrelated files can bury the details that matter, and every model has a limit on how much it can hold at once. Common techniques are: Search and retrieval: let the agent search the repository or documentation instead of loading everything up front. Summarizing long tool output: keep the useful lines of a 5,000-line test log, not all of it. Compaction: when the conversation gets long, replace older history with a short summary. Notes for later: write key findings to a file the agent can re-read. Sub-agents with clean context: hand a side task to a separate agent and take back only its short answer. Practical takeaway: Give the agent a clear path to the information it needs, and keep its working context focused. 3. Tools and execution: let the agent act safely Tools let an agent do more than generate text. The harness decides where those actions run and what the agent can access. For example, it might let an agent edit files in an isolated workspace while blocking access to production systems, and require human approval before actions with external consequences. Clear tool names, simple inputs, and error messages the model can act on make tools easier to use correctly. Practical takeaway: Give the agent only the tools and permissions needed for its task. 4. Durable state: preserve progress between sessions A model’s active context is temporary. If the plan and progress exist only in the conversation, the next run may repeat work or make wrong assumptions. A harness can save a task plan, decision log, test results, or a summary of what is done and what remains, so the next session has a reliable place to resume. Practical takeaway: Save progress outside the model’s temporary context. 5. Orchestration: manage the sequence of work Orchestration controls how an agent moves through a task: which step comes next, whether a failed action is retried, and when the agent should stop or ask a person. Multiple agents can help when tasks divide cleanly, but adding agents does not automatically improve the result. Each needs a clear role, enough context, and a way to check or combine its work. Practical takeaway: Add workflow steps and handoffs to solve a real coordination need, and keep the process as simple as the task allows. 6. Verification and observability: check the work and understand failures An agent’s final message is not proof that its work is correct. The harness needs checks that provide evidence, such as tests, type checks, build results, or evaluations. Observability, meaning tool-call histories, logs, and traces, shows where the agent went wrong and helps teams improve the system. Practical takeaway: Define what “done” means before the agent starts, and check the result with evidence. Security and Cost Limits An agent that can run commands and read files can also make mistakes at speed. A harness should limit the damage and keep the loop bounded. Security: treat the agent as an untrusted worker Sandboxing: run actions in an isolated environment with no access to production systems or secrets it does not need. Least privilege: give each tool the narrowest permissions that work, for example read-only database access unless writes are required. Approval gates: require a person to confirm actions that are hard to undo, such as deleting data, sending messages, or deploying. Prompt injection: text the agent reads, such as a web page, an issue comment, or a file, can contain instructions that try to steer it. Treat all outside content as data, keep sensitive tools away from steps that read untrusted text, and require approval before risky actions that follow it. Audit trail: log every tool call so you can review what the agent did. Cost: keep the loop bounded Step and time limits: stop after a set number of steps or minutes and report where things stand. Token budgets: cap how much context and output a task may use. Retry caps: retry a failed action a few times, then escalate instead of repeating it forever. Right-sized models: use a smaller, faster model for simple steps and a stronger one for hard decisions. Practical takeaway: Assume the agent will sometimes be wrong or misled, and design permissions and limits so a mistake stays small and cheap. Our Mini Harness: Architecture Now let us put these ideas into code. The task is a bug where a checkout function applies a discount twice. The agent must fix it without editing the tests. Each part of the diagram maps to a layer from the previous section: Part Layer What It Does in Our Code Build context Instructions, context Loads AGENTS.md into the system prompt and clips long tool output Tool gate Tools and execution Keeps paths inside the workspace and makes tests/ and AGENTS.md read-only Verify Verification Runs the tests itself before accepting “finish” State file Durable state Saves each step and the final status to .harness/state.json Step limit Orchestration, cost Stops the loop after a set number of steps The model is swappable. We will use a scripted model that plays back fixed actions, so the demo runs offline and gives the same output every time. We will also show a small adapter for a real model. Hands-on Implementation of a Mini Harness Everything below lives in one flat file, harness_demo.py, which comes with this guide. You can read it top to bottom, or run it as is. Install Dependencies The offline demo uses only the Python standard library (Python 3.9 or newer), so there is nothing to ins [truncated for AI cost control]