cleandataengineering.aiAgent Harness, drawn simply
You are here: Tech stack › L3 · Tool layer

Agent Harness Tutorial · Tech stack

L3 · Tool layer

Actions through typed tools, checked before they run. Family: Act · one turn, in order.

AZURE OPTIONSMCP servers on Container Apps✓ usedAPIM in front of MCP◐ planned: tier 10Foundry tools· considered: not pickedOUR CHOICEMCP Python SDKclient + claims serverjsonschemaarguments checkedOur gating, keys, size capsOPEN-SOURCE OPTIONSMCP Python SDK✓ used: open protocolFastMCP· consideredWHO DOES THE WORKAzure gives 25% · we code once 35% · each agent team still does 40%
Dark boxes are what we run. Solid boxes are used or planned; dashed boxes were considered or dropped (crossed). The bar: grey is what Azure gives, dark is what we code once, hatched is what each agent team writes.
Why our choiceMCP is an open protocol and the only path to the claims system; our _meta keys carry scope, side effect and idempotency.
OptionWhere fromVerdictWhy
MCP Python SDKours✓ chosenclient + claims server
jsonschemaours✓ chosenarguments checked
Our gating, keys, size capsours✓ chosen
MCP servers on Container AppsAzure✓ used
APIM in front of MCPAzure◐ plannedtier 10
Foundry toolsAzure· considerednot picked
MCP Python SDKopen source✓ usedopen protocol
FastMCPopen source· considered

How it works inside the harness: Tool call.

Compared: How does the agent call tools?

MCP Python SDK (m…open sourcechosenFastMCPopen sourcealternativeFunction tools in…open sourcerejectedOpenAPI / REST to…open sourcerejectedAPIM REST-as-MCPAzurerejectedFoundry toolsAzureonly on Foundry
Dark: what we chose. Crossed and dashed: rejected or not for us. Added here (not a Series table).
OptionFromVerdictWhat it isProcess boundaryPer-tool metadataAuth on every callVerdict reason
MCP Python SDK (mcp)open sourcechosenofficial MCP client and serveryes: its own server_meta: side effect, scopebearer token checked againMCP is the only path
FastMCPopen sourcealternativehigher-level MCP server libraryyesyesyes, via its authlisted beside the official SDK
Function tools in processopen sourcerejectedPython functions given to modelno: same processonly what we addinherits the agent's rightsno far-end checks
OpenAPI / REST toolsopen sourcerejectedHTTP API described by OpenAPIyesno standard placeyesnot shaped by intent
APIM REST-as-MCPAzurerejectedAPIM exposes REST as MCPyesnoat the gatewaywraps REST, not intent
Foundry toolsAzureonly on Foundrytools in Foundry Agent ServiceFoundry runs themFoundry's ownFoundry connectionsonly if the loop moves there
DecisionTools are dedicated MCP servers built with the official MCP Python SDK, each tool declaring its side effect and required scope, and the far end checks the token again. We would put APIM in front as the MCP front door, but never use REST-as-MCP for agent-facing tools.

How it is done: the real code

Cut from the live repositories each time the site is built, so it always matches what runs.

    async def invoke(
        self,
        name: str,
        arguments: dict[str, object],
        *,
        caller: Identity,
        idempotency_key: IdempotencyKey | None = None,
    ) -> ToolResult:
        """Both MCP failure channels, kept apart — and the caller carried with the call.

        The session travels as request metadata, not as an argument: the model
        writes the arguments, and whose session this is must never be something
        the model can say.

        A protocol error (unknown tool, malformed request) raises and surfaces
        here; an execution error comes back as an ordinary result with
        `is_error` set. An agent that handles one and not the other looks
        healthy until production.
        """
        try:
            # MCP's `_meta` is an open object; the SDK's TypedDict names only the
            # progress token. The cast states that gap rather than hiding it.
            fields: dict[str, object] = {SESSION_META: await self._session(caller)}
            if caller.grant is not None:
                fields[APPROVAL_META] = caller.grant
            if idempotency_key is not None:
                fields[IDEMPOTENCY_META] = idempotency_key.value
            meta = cast(RequestParamsMeta, fields)
            raw = await self._client.call_tool(name, arguments, meta=meta)
        except Exception as exc:
            # Into the model's context, so scrubbed first: a far end's error can
            # quote the token or key it refused (AHC-0035, F-074). The kind of
            # failure stays, because the model chooses its next step by it.
            said = f"{type(exc).__name__}: {redact(str(exc))}"