Agent Harness Tutorial · End to end · Zoom level 2
Tool call
When the model asks for a tool, the harness, not the model, makes the call. On the way it checks the request, makes sure a write can only happen once, and cuts the result down to size before the model sees it.
Reads and writes are treated differently. Reads (like list_claims) can run side by side, up to 4 at once, and need no ledger row. Writes (like register_claim) run one at a time, in the model's order, and each one first claims a row in the ledger.
Mistakes become results, not crashes. An unknown tool name or bad arguments come back to the model as an error result it can read and correct on the next trip.
MCP (Model Context Protocol) is the standard way the harness talks to the claims system's tools. The claims system takes the customer from the token, never from anything inside the message.
list_claims({{}}), key run_74e1…:0:1, 51 ms, outcome ok, 9 claims returned.Code view: input, process, output, the call stack, the classes
How it is done: the real code
Cut from the live repositories each time the site is built, so it always matches what runs.
agent_harness/tools/__init__.py:124GatedTools.call: check, record, call, trim async def call(
self,
name: str,
arguments: dict[str, object],
identity: Identity,
idempotency_key: IdempotencyKey,
) -> ToolResult:
registry = await self.list_tools(identity)
spec = registry.get(name)
if spec is None:
# AACP-0023. Counted before it raises, because no tool span opens
# for it; under one label, because the name is the model's words.
tel.counters.tool_calls.add(1, {"tool": UNOFFERED, "outcome": "unknown"})
raise UnknownTool(name, tuple(t.name for t in registry.tools))
with tel.span(
"agent.tool",
**{
tel.GEN_AI_TOOL_NAME: name,
tel.SIDE_EFFECT: spec.side_effect.value,
tel.IDEMPOTENCY_KEY: idempotency_key.value,
},
) as span:
tel.set_payload(span, tel.TOOL_ARGUMENTS, json.dumps(arguments, sort_keys=True))
started = time.monotonic()
outcome = "error"
try:
result, outcome = await self._dispatch(
name, arguments, identity, idempotency_key, spec, span
)
# JSON, so a rule reading the record can compare fields rather
# than parse a rendering (AHC-0114's fourth group).
shown = result.structured if result.structured is not None else result.text
tel.set_payload(span, tel.TOOL_RESULT, json.dumps(shown, default=str))agent_harness/loop/dispatch.py:32Reads side by side, writes one at a timeasync def dispatch(
tools: ToolClient,
planned: list[tuple[ToolCall, IdempotencyKey]],
identity: Identity,
local_tools: Mapping[str, LocalTool],
registry: ToolRegistry,
fan_out: int,
) -> list[ToolResult]:
"""Reads concurrently, everything else in the order the model asked.
A read that fails costs a retry. A write that fails halfway through a
parallel batch costs a reconciliation, in an order that depended on
scheduling — and a compensating path is far easier to reason about when the
writes happened one at a time.
"""
from agent_harness.contracts import SideEffectClass
def is_read(call: ToolCall) -> bool:
spec = registry.get(call.name)
return spec is not None and spec.side_effect is SideEffectClass.READ
if len(planned) > 1 and all(is_read(call) for call, _ in planned):
thunks: list[Callable[[], Awaitable[ToolResult]]] = [
partial(_invoke, tools, call, identity, key, local_tools) for call, key in planned
]
return await flw.gather_bounded(thunks, limit=fan_out)
return [await _invoke(tools, call, identity, key, local_tools) for call, key in planned]config/azure.yaml:79The tool port on Azure tool_runtime:
adapter: mcp-client
url: {env: CLAIMS_MCP_URL}Tech choices (what we chose, Azure and open-source options): L3 · Tool layer