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