Engineering resource
Enterprise AI Tool Contract Lab
Run an offline Python example that tests tool permissions, tenant boundaries, approval binding, duplicate calls and audit evidence against a fake CRM.
A tool’s argument schema cannot establish who is allowed to invoke it. This small executable lab separates a proposed action from trusted identity, approval and replay state. It makes one fake CRM operation observable enough to test those boundaries.
The example accompanies Tool Contracts for Enterprise AI Agents. It runs locally with Python’s standard library and changes only in-memory demonstration records. No service account, API key, network access or repository account is needed.
Run the example
Extract the ZIP and run:
1 | python3 tool_contract_lab.py --test |
The demo performs one approved update, then repeats the same request. The second result has replayed: true, and the fake CRM write count remains 1. The test suite also submits twenty identical requests concurrently to the same gateway instance.
Follow the trust boundary
The caller supplies case_id, new_status, an idempotency key and an approval identifier. It cannot grant itself permissions by adding an argument. The application injects a trusted principal, looks up the approval record, and scopes the case lookup to the principal’s tenant.
| Check | What the lab verifies | Where the evidence appears |
|---|---|---|
| Argument shape | Unknown fields, malformed case identifiers and unsupported statuses are rejected. | Explicit Python validation and the documented JSON contract. |
| Authority | The expected agent and cases:write scope are required. | Permission-denial tests, including a replay after authority is removed. |
| Tenant boundary | A principal cannot reach a case from another tenant. | A denied lookup with no business write. |
| Approval | A new write requires an unexpired approval bound to actor, tenant, tool version and exact arguments. | Expiration and changed-action tests. |
| Replay | The same key and action return a stored result; another action using that key is rejected. | Sequential and concurrent duplicate tests. |
| Audit | Execution, replay and denial have distinct structured records. | Decision records, action hash, and before/after status for execution. |
The argument shape is also described using JSON Schema. Its object documentation explains properties, required and additionalProperties. The lab explicitly checks its own fixed schema in Python; it does not implement a general JSON Schema engine.
Distinguish replay from a new authorization
A replay still checks the current principal and resource boundary. It returns the previously stored outcome without another write. It does not need a fresh approval for that completed action. A new request key is a new attempted execution and must pass the approval checks.
The approval store is a trusted fixture, not a caller-supplied assertion. Replacing that store with a client-provided approval object would remove the boundary the lab is intended to demonstrate. Use the AI governance architecture guide to place the identity and approval services in a larger system.
Know what the example does not prove
The lock covers one process, a fake mutation and an in-memory replay record. Restarting the process loses that state. Real API calls introduce uncertain responses, crashes between the external write and local persistence, and multiple gateway workers. Those need durable records and downstream idempotency or reconciliation; the sample does not provide an exactly-once guarantee for external effects.
For a real implementation, connect the review to audit-log architecture, eval gates and incident response. Keep the business operation, permission policy and failure evidence specific to the workflow you are deploying.
Explore the wider reading path in Enterprise AI Architecture & Governance.