What is an agent harness? How agent harnesses work
A model can suggest a code change, but completing the task requires something to read the repository, run commands, inspect failures, and preserve progress. Once those actions can affect files or services, your team also needs control over what the agent may access and when it must stop.
An agent harness is the software around a model that manages this work through tools, context, execution, and an ongoing feedback loop. Understanding how these pieces work together helps you choose a harness, control its access, and decide where to run it.
An agent harness coordinates model calls, tool execution, context, and task state so an AI agent can work through a task over multiple steps.
- Separate the model's proposed action from the software that authorizes and executes it.
- Give the agent tools and an execution environment suited to the task, with bounded access and resources.
- Preserve useful progress across interruptions, while distinguishing saved files from conversation history and running processes.
- Check results against task requirements and stop on completion, failure, cancellation, or a defined limit.
If your team needs a controlled cloud workspace for coding agents, Northflank Harnesses provides isolated coding environments on managed infrastructure or in your own cloud. Northflank supplies the workspace; your chosen coding agent manages the model calls and tool loop.
Get started with Northflank self-serve, or book a demo to discuss coding-agent workspaces, access, and deployment requirements.
An agent harness connects a model to the tools, context, and execution environment it needs to complete a task.
The model interprets the task and proposes a response or tool call. The harness assembles the request, dispatches permitted tools, handles their results, and controls whether another model call follows. Depending on the task, it may also need saved progress, approval checks, delegation, and tests.
Harnesses package these components differently, so check which ones your chosen tool includes.
| Component | Responsibility | Example |
|---|---|---|
| Model interface and loop | Send requests and continue or stop the run | Ask for another action after a test fails |
| Context management | Select the information available to the model | Load relevant files and summarize earlier work |
| Tool layer | Expose operations and validate their inputs | Read a file or call an approved API |
| Execution environment | Provide the resources where operations run | Execute tests in an isolated workspace |
| State and persistence | Retain information needed to continue | Save task progress and artifact references |
| Permissions and intervention | Apply action rules and request help when needed | Require approval before a production change |
| Evaluation and telemetry | Check outcomes and record observable activity | Associate test results with a run and code revision |
Check how your harness enforces permissions and saves progress before relying on either. A short task may need little more than a tool loop. A coding task that spans sessions also needs saved progress and checks that the work still runs.
Agent harnesses work by repeatedly giving a model context, executing permitted actions, and feeding observations back until the run reaches a stopping condition.
A typical run moves through the steps below, sometimes combining them or running independent tools at the same time.
The harness prepares the model's input from the user's request, system instructions, available tools, and relevant task information.
For a coding task, that might include repository guidance, selected source files, the current branch, and previous test output. Loading every file into the prompt is rarely a useful starting point. Give the agent ways to retrieve additional information as it discovers what the task requires.
Define the expected result early. “Fix pagination without changing the response schema” gives the run a more useful completion condition than “improve this API.”
The model receives the assembled context and returns a response or a request to use a tool. A tool request identifies an operation and its arguments, such as a file path or shell command.
The harness interprets that output. The model may propose reading a test file, but the tool implementation performs the read. Keeping those responsibilities separate helps your team distinguish an intended action from one that actually happened.
A harness with permission controls checks each requested action against its configured rules, then allows it, blocks it, or asks for approval.
Validate tool arguments and restrict access both where the code runs and in the services it calls. A prompt asking the model to avoid production cannot replace a credential that lacks production access. Keep policy administration and emergency shutdown outside the agent's writable workspace.
If developers need to inspect an app while an agent works, Northflank provides Harness networking configuration with public or private ports. Choose a private port for internal access or a public port when the app needs to be reachable over the internet.
The tool returns a result, such as file contents, an API response, or a command's exit status and output. The harness adds the relevant observation to the next model request.
A failing test can change the next action. The agent may inspect another function, revise its patch, or ask for missing information. Each result helps the agent decide what to do next.
Keep output bounded and treat retrieved content as task data. A repository file or tool response should not be able to grant new permissions simply by containing instructions.
Longer tasks need a way to retain progress when context fills up or execution stops. Depending on the implementation, this can involve conversation summaries, saved task state, progress files, commits, and references to outputs.
Keep track of what the model can currently see, what the application has saved, and what remains in the workspace. Restoring one does not automatically restore the others.
If your team needs to stop compute between coding sessions, Northflank provides Harness pause and resume. Files under /home/harness survive, while terminal sessions and processes stop. When you return, restart the processes you need and use your coding agent's session recovery if it supports it.
The harness ends the loop when the agent finishes, a limit is reached, a failure prevents progress, or a user cancels it.
Before accepting the result, check the work behind the model's completion message. For a coding task, review the changes and test results. For a data-processing task, check that the output has the expected structure and accounts for the input records.
Record the final status and retained artifacts, then apply your workspace and credential cleanup policy. For the wider execution architecture, see what infrastructure AI agents need to run code safely.
A coding agent fixing a pagination bug shows how the model, harness, and environment work together.
Suppose your task is to correct an endpoint that repeats the last item of one page at the start of the next. The agent may edit the relevant code and tests, but has no production credentials.
The harness makes repository-reading and test-execution tools available. The model requests the endpoint and its tests, then proposes a regression test. Running that test produces a failure showing the duplicate item. The harness returns the result, and the model uses it to propose a patch.
After the patch, the agent runs the regression test and relevant existing tests. The agent should finish by showing you what changed, which tests passed, and what still needs attention. If execution stops halfway through, its saved progress should make the remaining work clear.
Review the fix against the task requirements before accepting it. Deployment follows your release policy. If your team needs to connect reviewed changes to builds and releases, Northflank provides Workflows with build, deployment, condition, and approval nodes.
An agent harness coordinates the working agent, a framework supplies building blocks, and a sandbox provides an isolated place to execute code.
These categories overlap. A framework can include a ready-made harness, and a coding product can bundle the model interface, tools, and runtime experience. Check which parts you get out of the box and which your team still needs to build or operate.
A sandbox alone does not assemble model context, interpret task progress, or decide when the work is complete. A harness using shell tools still needs an execution boundary appropriate to the code it runs.
The Model Context Protocol, or MCP, connects an AI application to tools and contextual resources through a common interface. A harness can use MCP integrations within its tool layer while retaining responsibility for the overall task loop.
Try an agent harness on tasks your team actually performs, including runs that fail or need to be interrupted.
Before giving it broader access, check how it handles these situations:
- Task completion: Does it finish the task and show how it checked the result? Test incomplete work and misleading success messages as well as the happy path.
- Recovery: Can it continue after interruption without losing necessary state? Check whether retrying an external write could create duplicate effects.
- Authority: Can your team restrict tools, credentials, destinations, and workspace access? Test malformed arguments and instructions embedded in untrusted content.
- Investigation: Can you connect a request to its tool calls, execution results, and affected resources? Keep sensitive content out of routine logs.
- Resource control: Can you bound model use, tool duration, retries, and concurrency? Include workspace runtime and retained storage when estimating costs.
Your AI-agent execution audit trail should distinguish proposed actions, permitted actions, and observed effects. A terminal transcript alone leaves gaps in that explanation.
Choose an existing harness when its tools and behavior fit the task. Build custom orchestration when your application needs a different interaction or control model. In either case, decide separately who will operate the execution environment.
Northflank Harnesses gives your coding agents cloud workspaces. If you are building your own agent application, you can use Northflank Sandboxes to create and manage its code-execution environments programmatically.
Northflank is an AI-agent sandbox and workload platform for running untrusted code in isolated environments on Northflank Cloud or in your own cloud account and VPC.
Northflank provisions the environment; your team chooses the agent and configures its access, resources, and tools.
To start, use a Pay As You Go account and a coding-agent account or API key. Create a Harness in a project, select and authenticate your agent, and optionally connect a repository through a Git integration. Access it through the dashboard or SSH with an authenticated Northflank CLI. Team members can work in the same environment. Follow the Harness quickstart for setup.
You can adjust the Harness configuration, including its runtime image, resources, storage, and environment variables, and inspect CPU and memory usage. Export work you intend to keep before permanently deleting the Harness and its workspace.
Northflank Harnesses is a good fit when your team wants coding agents to work with its repositories, keep files between sessions, and run on managed infrastructure or in your own cloud.
With Bring Your Own Cloud (BYOC), you can run your coding workspace and store its files in your own cloud account and VPC. You own the infrastructure; Northflank provisions and manages Kubernetes.
Get started with Northflank self-serve, or book a demo to discuss your coding-agent workflow and infrastructure requirements.
A harness can start with a simple tool loop and grow as your tasks need more control.
A prompt supplies instructions. Software must still call the model, execute tools, return results, and manage the run. A small application can implement that loop, but the prompt alone does not perform it.
It enables repeated action without requiring a new user message at every step. You control how much it can do through its tools, permissions, stopping conditions, and opportunities for human intervention. It does not guarantee successful task completion.
No. One model-driven loop can handle a multistep task. Add delegation when separate work benefits from its own context or parallel execution, and account for the extra coordination and resource use.
Harness engineering is the work of designing and improving the software around a model: tool interfaces, context handling, state, controls, and evaluation. It changes how the agent operates without necessarily changing the model's weights.
Continue with these guides to the infrastructure and controls around agent workflows:
