エージェント行動をコードにマッピングするハンドブック

Agent Harness · Tencent HY LLM Frontier · June 2026

Making agent harnesses understandable, auditable, and editable.

Open an open-source coding-agent codebase and you may want to see how it actually runs, verify that it behaves as safely as the documentation claims, or adapt it into an agent of your own. These goals sound different, but once you are in the code they all reduce to concrete questions about behavior. Will the agent ask before deleting a file, for example? Answering that means finding the confirmation logic, tracing bypass paths, and identifying every implementation site a change would touch. In a repository with thousands of files, searches for *delete*, *permission*, or *confirm* return scattered fragments—and piecing them back into a full behavior chain is hard work.

The problem is not missing code, but missing a path from behavior to implementation. What is needed is not another code index, but a map that connects the two. Harness Handbook organizes scattered implementation into a behavior-level manual: it structures execution around system behavior and links every step to verifiable code evidence. Users can ask directly what they want to understand, audit, or change, and the Handbook locates the relevant behavior units, implementation sites, and next steps. As the harness evolves, this map keeps the system understandable and reviewable—and keeps humans in the loop throughout.

Ruhan Wang1,2,* · Yucheng Shi1,† ·

Zongxia Li1,3 · Zhongzhi Li1,4 ·

Yue Yu2 · Junyao Yang1,5 ·

Kishan Panaganti1 · Haitao Mi1 ·

Dongruo Zhou2 · Leoweiliang1

1 Tencent HY LLM Frontier · 2 Indiana University ·

3 University of Maryland · 4 University of Georgia ·

5 National University of Singapore

• Corresponding author: Ruhan Wang (ruhwang@iu.edu)

† Lead project collaborator

At a glance

• The problem Harness Handbook addresses. A harness shapes how agent behavior unfolds, yet that behavior is often implicit and buried in complex code. Harness Handbook organizes it into a navigable, verifiable behavior map.

• Reading a harness. The Handbook explains how a harness runs in terms of system behavior, then links those explanations back to code evidence—so readers need not start from a file tree and disconnected source fragments.

• More reliable harness changes with coding agents. The Handbook maps natural-language change requests to the relevant behavior units and implementation sites, helping the agent skip irrelevant searches, miss fewer dependencies, and produce a tighter edit plan.

• Building your own agent on an existing harness. By presenting the harness’s behavior and capabilities in natural language, the Handbook lets users understand and adjust the system without wading through low-level code—and build an agent that fits their needs.

Part 01

Why does an agent harness need a behavior-level manual?

When people talk about AI agents, they often start with model capability. Once an agent starts doing real work, however, the question quickly shifts from “what can the model do?” to “what will the system allow it to do?” Whether a command runs, whether the user is asked before a file is deleted, and how failures are handled are decided not only by the model, but also by the harness that surrounds it.

To understand how these behaviors arise, you have to examine the harness itself. Doing so comprehensively is difficult in production. Codex, for example, coordinates the model, tools, state, permissions, and execution environment to turn each user request into a sequence of real actions—but the relevant implementation is spread across 2,267 files, more than 34,000 functions, and nearly 160,000 code connections. At that scale, a file tree shows where code lives, but not how those pieces work together to produce a behavior.

Directories and search results alone cannot reconstruct a complete behavior. What we need is a different way to read the system: start from behavior, then trace back to source code for verification. That approach serves three goals.

Understand

See how the harness runs

Follow one request through the full flow: what the model receives, when tools are called, how state moves, and how the system responds to failure.

Audit

Verify that behavior matches expectations

Trace the actual execution path to check permissions, confirmation logic, sandboxing, and data flow, including unusual routes that might bypass those protections.

Adapt

Build your own agent

First see which capabilities the harness already provides and which behaviors and code support them, then extend or adjust the system for your own needs.

All three goals begin with a specific behavior and then return to the code for evidence. The difficulty is that behavior and code do not map one-to-one: one behavior is often determined by implementation scattered across several modules.

Part 02

Why is one behavior scattered across so many locations?

“Ask the user before deleting a file” sounds like a simple rule. To verify how it works in code, however, you must follow a chain of decisions: does the model request confirmation, can the tool call be intercepted, where is the user’s choice recorded, and under what conditions is the deletion finally executed? Any link in that chain can change the outcome.

Each implementation site controls only one part of the chain. No single confirmBeforeDelete() function represents the complete behavior. You have to trace prompts, tool wrappers, permissions, and state through to sandbox execution and fallback paths before you can tell whether the request will run, be rejected, or enter another flow.

So when you ask, “Will it really ask me before deleting a file?”, you are not running a keyword search—you are reconstructing a behavior chain and finding code evidence for every decision along it. We call this behavior localization. How completely you reconstruct that chain shapes the explanation, the risk review, and the change boundary. Harness Handbook turns behavior chains hidden in the codebase into a map you can browse layer by layer and verify against source code.

Part 03

Harness Handbook: a navigable behavior map

Because a single behavior can span many implementation sites, the Handbook cannot simply repackage the file tree. Harness Handbook represents the harness in behavior-centric terms, using L1, L2, and L3 to narrow the question step by step. Every level preserves verifiable code evidence, so readers can check each explanation and ground later edits in source.

L1 · System overview starts with a global view of the harness. Instead of listing files and functions, it follows one request through the system: how the request enters, which stages it passes through, how state moves between them, and how model output becomes a real action. It first answers: *How does this harness run as a whole?*

L2 · Behavior-unit overview then breaks that system flow into behavior units. Each unit captures a coherent class of behavior and records its responsibilities, inputs and outputs, dependencies, and key state. At this level, readers can see how complex behavior is decomposed and how the pieces reconnect within the end-to-end flow.

L3 · Behavior-unit detail finally zooms into one unit: when a behavior is triggered, how it executes, how state changes, which path is taken after an exception or failure, and which files and functions provide the evidence. Here, “confirm before deleting a file” is no longer a standalone rule—it is a behavior chain whose individual decisions can be verified one by one.

An example L3 behavior unit

Return to the example of “confirm before deleting a file.” The L3 entry below expands that one-line rule into a behavior unit that can be checked item by item, covering both the normal execution path and edge cases that need separate review.

Part 04

How is the behavior map generated from code?

The three-level structure determines how the Handbook presents behavior, but the map is trustworthy only if every

explanation traces back to real code. It cannot be built by asking a model

to summarize files one by one. Generation follows a facts-first rule instead: natural language explains

behavior, while every claim stays anchored in code facts—not model guesswork.

1

Extract facts

→ program graph

The first step extracts static program facts: files, functions, classes, call

relationships, state reads and writes, configuration boundaries, and external API

calls. Together they form a program graph that connects the harness’s otherwise

scattered implementation elements and provides the factual basis for organizing behavior.

2

Organize by behavior

→ behavior map

The second step reorganizes the program graph into a behavior map. It sketches a coarse

execution skeleton of the harness lifecycle, then maps functions, modules, and code

regions to the corresponding stages and behavior units. Because the first mapping may be

imperfect, a proposer–reviewer loop repeatedly corrects it until the stages, unit

boundaries, and code evidence align.

3

Synthesize the handbook

→ handbook

Finally, the converged map is rendered as the system overview, behavior-unit overview,

and behavior-unit detail. The explanations may be generated in natural language, but

every source link, function reference, and code snippet must come from the extracted

program facts. In short, prose explains; facts anchor—and every behavior chain can be checked in the code.

Part 05

How do you get from a behavior question to code evidence?

Once the behavior map exists, readers can start from a specific question and work toward code evidence layer by layer—without searching the entire repository first. We call this Behavior-Guided Progressive Disclosure (BGPD): L1 supplies system context, L2 locates the relevant behavior units, and L3 opens the verifiable implementation details.

1 · BEHAVIOR QUESTION

“Before deleting a file,

must it confirm?”

2 · L1 SYSTEM OVERVIEW

prose + lifecycle diagram

input

plan

tool execution

observe

finalize

3 · L2 UNIT OVERVIEW

unit map · roles & functions

Delete guard

3 fn

Permission rule

1 fn

State record

2 fn