Module Contract

Context

As the modules an agent uses multiply, what each module accepts, what it returns, and when it fails becomes tacit knowledge. Replacing a module or reusing it from another agent then triggers errors no one predicted.

Problem

Without a documented interface you have no basis for evaluation and no compatibility guarantee on replacement. An unclear authority scope lets a module produce side effects beyond what was intended; an undefined failure condition means the agent has no way to detect or recover from failure.

Forces

• A detailed contract is safer but constrains module flexibility.
• Defining the contract first lets you validate design before implementation, but early requirements are unstable.
• Runtime validation increases safety at the cost of performance.

Solution

Give every module an explicit contract: input schema, output schema, required authority, failure conditions, and the shape of the failure response. The contract must live in both code and documentation, and contract violations must be detectable at runtime. When adding or replacing a module, validate contract compatibility first. Anthropic's [Building Effective Agents] calls this interface the Agent-Computer Interface (ACI) and argues that we should invest in agent interface design the way we invest in human interface design — applying Poka-yoke (constraints that make misuse hard) to structurally prevent agent misuse. Contracts are not static documents. As in the Generator-Evaluator negotiation model from Anthropic's [Harness Design for Long-Running Application Development], contracts between agents can be negotiated and updated dynamically.

Application scenario

Illustrative scenario — figures and company names in this page are hypothetical for explaining the pattern, not measured data.

A response-generation module used by the Response Agent. Contract: input is { category: string, context: string, tone: 'formal' | 'casual', maxTokens: number }; output is { response: string, confidence: number, sources: string[] }. Required authority: read access to the knowledge base. Refusal condition: if category falls under legal advice, refuse and return an escalation code. With this contract, swapping in a different LLM-backed module only requires confirming the new module honors the same schemas and refusal condition.

How it breaks

Running modules without contracts produces failures like "we changed the LLM and the response format shifted, so the QA Agent can't parse it" or "the new module answers legal-advice questions, so compliance just opened a ticket." Without defined failure conditions, agents treat bad output as good and proceed downstream.

Academic References

• ISO/IEC 25010 — Systems and Software Quality Models
• Practices for Governing Agentic AI Systems — OpenAI