Module Contract

Context

에이전트가 사용하는 모듈이 늘어나면, 각 모듈이 무엇을 받고 무엇을 돌려주는지, 어떤 조건에서 실패하는지가 암묵적 지식으로 남는다. 이 상태에서 모듈을 교체하거나 다른 에이전트에서 재사용하면 예상치 못한 오류가 발생한다.

Problem

모듈의 인터페이스가 문서화되지 않으면 평가 기준을 세울 수 없고, 교체 시 호환성을 보장할 수 없다. 권한 범위가 불명확하면 모듈이 허용 범위를 넘는 부작용을 일으키고, 실패 조건이 정의되지 않으면 에이전트가 실패를 감지하거나 복구할 방법이 없다.

Forces

• 계약이 상세할수록 안전하지만, 지나치게 엄격하면 모듈의 유연성이 떨어진다.
• 계약을 먼저 정의하면 구현 전에 설계를 검증할 수 있지만, 초기에는 요구사항이 불안정할 수 있다.
• 런타임 검증을 추가하면 안전성이 올라가지만 성능 비용이 따른다.

Solution

모든 모듈에 명시적 계약을 부여한다. 계약에는 입력 스키마, 출력 스키마, 필요 권한, 실패 조건과 실패 시 반환 형태를 포함한다. 계약은 코드와 문서 양쪽에 존재해야 하며, 계약 위반은 런타임에서 감지 가능해야 한다. 새 모듈을 추가하거나 기존 모듈을 교체할 때는 계약 호환성을 먼저 검증한다. Anthropic의 [Building Effective Agents]는 이 인터페이스 층을 Agent-Computer Interface(ACI)로 부르며, 사람을 위한 인터페이스 설계에 투자하는 만큼 에이전트 인터페이스 설계에도 투자할 것을 제안한다 — 특히 Poka-yoke 원칙(잘못 사용하기 어렵게 만드는 제약 설계)을 적용해 에이전트의 오용을 구조적으로 차단하는 접근이 그 사례다. 계약은 정적 문서에 머무르지 않는다. Anthropic의 [Harness Design for Long-Running Application Development]에서 소개된 Generator-Evaluator 협상 모델처럼, 에이전트 간 계약은 동적으로 협상되고 갱신될 수 있다.

적용 시나리오

예시 시나리오 — 본 페이지의 수치와 기업명은 패턴 설명을 위한 가상 사례이며, 실측 데이터가 아닙니다.

Response Agent가 사용하는 응답 생성 모듈의 계약 예시: 입력은 { category: string, context: string, tone: 'formal' | 'casual', maxTokens: number }이고, 출력은 { response: string, confidence: number, sources: string[] }이다. 필요 권한은 '지식 베이스 읽기'이며, 거절 조건은 'category가 법률 자문에 해당하면 거절하고 에스컬레이션 코드를 반환한다'이다. 이 계약이 있으므로 응답 생성 모듈을 다른 LLM 기반 모듈로 교체할 때 동일한 입출력 스키마와 거절 조건을 충족하는지만 확인하면 된다.

이렇게 하면 무너진다

계약 없이 모듈을 운영하면 'LLM을 바꿨더니 응답 형식이 달라져서 QA Agent가 파싱에 실패한다', '새 모듈이 법률 자문 질문에도 답변을 생성해서 컴플라이언스 이슈가 발생한다' 같은 문제가 나타난다. 실패 조건을 정의하지 않으면 에이전트는 모듈의 잘못된 출력을 정상으로 간주하고 후속 처리를 진행한다.

Academic References

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