Microsoft Foundry Toolbox: versieer MCP-tools zonder je agent te breken

Een agent die tools gebruikt, hangt niet alleen af van een prompt. Een nieuwe toolversie kan parameters, permissions of een downstreamverbinding veranderen. Als iedere agent stilzwijgend de nieuwste versie volgt, wordt een kleine toolwijziging een moeilijk te onderzoeken release. Met Microsoft Foundry Toolbox kun je een versie eerst apart toetsen en daarna gericht promoveren.

De configuratie hieronder is een voorbeeld, geen uitgevoerde Azure-deployment. Microsoft beschrijft FoundryToolbox als beta. Controleer daarom endpointvormen en packageversies opnieuw op de dag dat je implementeert.

Wat is het verschil tussen een default- en een versie-endpoint?

Een consumer-endpoint volgt de default_version van een Toolbox. Een version-specifieke developer-endpoint wijst juist naar één immutable versie. Gebruik de tweede om te testen; gebruik de eerste pas voor de promotieroute.

# consumer: volgt de standaardversie
.../toolboxes/refund-tools/mcp?api-version=v1

# developer: pin op versie 2 voor contracttests
.../toolboxes/refund-tools/versions/2/mcp?api-version=v1

Volgens Microsoft krijgt een agent op de consumer-endpoint een nieuw gepromoveerde standaardversie zonder endpointwijziging of herdeploy. Dat is handig voor een beheerste rollout, maar maakt contracttests vóór promotion belangrijker. De Foundry Toolbox-handleiding adviseert een version-specifieke endpoint precies voor die test.

Welke grenzen moet je apart ontwerpen?

Ja, houd er minstens drie apart. Een agent die de Toolbox mag benaderen, heeft niet automatisch de rechten die een downstream-systeem nodig heeft.

Microsoft documenteert dat de agent de Toolbox-endpoint met zijn Entra-identiteit benadert, terwijl de Toolbox-tool apart bepaalt welke identity of credential downstream terechtkomt. Zet dus geen API-key of OAuth-token in de agentcode. Dat voorkomt bovendien dat een debugginglog per ongeluk een geheim bevat.

Stap 1: schrijf eerst een klein toolcontract

Gebruik een fictieve refund_preview-tool. Hij berekent alleen een voorstel; hij verandert geen betaling. Zo kun je een schemawijziging testen zonder een extern effect.

pattern: example
tool: refund_preview
version: "2"
expected_tools:
  - name: refund_preview
    required_arguments: [order_id, reason]
approval: always
must_not:
  - access_payment_credentials
  - create_refund

Lees op de vaste versie eerst tools/list. Controleer toolnaam, argumenten en de approval-metadata. Een tool die niet verschijnt, een onverwachte argumentnaam heeft of een extra write-tool aanbiedt, faalt de promotion.

const tools = await toolbox.listTools();
assert.hasTool(tools, "refund_preview");
assert.requiredArgs(tools, "refund_preview", ["order_id", "reason"]);
assert.approval(tools, "refund_preview", "always");

Dit is pseudocode. De test bewijst het contract van jouw gekozen versie, niet dat de downstreamservice correct is geautoriseerd.

Stap 2: behandel approval als runtimegedrag

Een belangrijke beperking staat expliciet in de Microsoft-documentatie: een Toolbox-endpoint blokkeert tools/call niet zelf als require_approval op always staat. De agentruntime moet vóór iedere call de toolnaam en argumenten tonen, wachten op de juiste beslissing en daarna precies die call hervatten of weigeren.

async function callWithApproval(call: ToolCall) {
  if (call.requireApproval === "always") {
    const decision = await requestApproval({
      name: call.name,
      arguments: call.arguments,
      callId: call.id,
    });
    if (decision.callId !== call.id || decision.status !== "approved") {
      return { status: "denied", reason: "APPROVAL_REQUIRED" };
    }
  }
  return toolbox.callTool(call);
}

Test een denied case naast een approved case. De denied test is geslaagd wanneer de tool helemaal niet wordt aangeroepen. Een systeem-prompt als “vraag altijd toestemming” is geen technische enforcement.

Stap 3: promoteer pas na een kleine releasegate

Een praktische releasegate voor deze demo bevat minimaal het volgende:

Promoveer daarna v2 naar default. Controleer op de consumer-endpoint dat de verwachte versie actief is en bewaar versie, timestamp, trace-ID en uitkomst als rolloutevidence. Log geen volledige orderargumenten. Bij een fout in één toolbron kan readiness falen omdat een Toolbox zijn bronnen samen inventariseert; Microsoft noemt dit als concrete diagnosehint.

Hoe draai je terug zonder paniek?

Een rollback is een besluit, geen verwijderactie. Houd de vorige gevalideerde versie beschikbaar. Als de default na promotion onverwachte tools, 401/403-fouten of contractverschillen geeft, zet je de eerdere versie opnieuw als default en blokkeer je nieuwe calls totdat de oorzaak vastligt.

Een versie-endpoint is hiervoor nuttig: je kunt de verdachte versie onderzoeken zonder dat elke consumer hem opnieuw gebruikt. Een rollback herstelt niet automatisch een toolcall met extern effect. Voor write-tools blijven idempotency, audittrail en zo nodig menselijke herstelactie nodig.

Wanneer is Toolbox niet de beste keuze?

Kies een eenvoudige service-integratie als je één stabiele API-call hebt en versioned discovery geen voordeel biedt. Kies geen defaultpromotion zonder contracttest als de tool betalingen, klantdata, toegangsrechten of productie-infrastructuur raakt. Voor private toolhosting met Entra en API Center is de Azure Functions MCP-server een ander, aanvullend patroon; voor protocolmigratie is MCP-server zonder sessies relevanter.

Voor een Azure-team dat tools, approvals en rolloutgrenzen als één ontwerp wil vastleggen, kan een Azure AI engineer helpen. De kern blijft: een versie is pas veilig als het gedrag, de identitygrenzen en de runtimepolicy samen zijn getoetst.