에이전트 설계 원칙
멀티에이전트 시스템에서 각 agent의 단일 책임, 입출력 계약, 도구 권한, 모델 선택 기준을 분리해 실패를 격리하고 운영 가능한 경계를 설계하는 방법을 정리합니다.
핵심 요약
- 좋은 agent는 "똑똑한 프롬프트"가 아니라 단일 책임, 계약 우선, 권한 최소화, 모델 전략 분리라는 4가지 원칙으로 설계합니다.
- 도구 권한·입력 컨텍스트·출력 형식·실패 격리 중 둘 이상이 다르면 agent를 분리할 가치가 큽니다.
- 계약에 goal, inputs, constraints, tools, output schema, escalation rule을 구조화해두면 orchestrator가 상태 전이를 기준으로 다음 동작을 정합니다.
- 모델은 책임 뒤에 붙는 선택지입니다. 라우터는 저렴한 모델, evaluator는 일관성 높은 structured output 모델로 역할에 맞춥니다.
- 되돌리기 어렵거나 규제 리스크가 큰 작업에는 human gate를 계약의 escalation rule에 넣습니다.
좋은 agent는 "똑똑한 프롬프트"가 아니라 좁은 책임, 명확한 계약, 제한된 권한으로 정의됩니다. 오케스트레이션이 복잡해질수록 agent 설계에서는 기능 목록보다 경계 정의가 더 중요합니다.
설계 원칙 4가지
| 원칙 | 의미 | 실무 판단 기준 |
|---|---|---|
| 단일 책임 | agent마다 한 가지 주요 결과에 집중 | 하나의 산출물을 한 문장으로 정의 가능 |
| 계약 우선 | 입력, 출력, 실패 형태를 먼저 정의 | 자연어가 아니라 구조화된 인터페이스 사용 |
| 권한 최소화 | 필요한 tool만 제공 | read와 write를 기본적으로 분리 |
| 모델 전략 분리 | agent의 책임과 모델 선택을 분리 | 고가 모델은 필요한 agent에만 사용 |
agent 경계와 계약 흐름
agent를 나누는 기준
agent를 역할 이름으로 나누지 말고 다음 질문으로 경계를 정합니다.
- 서로 다른 도구 권한이 필요한가
- 입력 컨텍스트가 완전히 다른가
- 출력 형식과 성공 기준이 다른가
- 실패했을 때 격리해야 하는가
이 네 가지 중 둘 이상이 Yes면 분리할 가치가 큽니다.
권장 계약 구조
| 항목 | 예시 | 설명 |
|---|---|---|
| goal | refund policy answer | 이 turn에서 해결해야 할 목표 |
| inputs | 고객 질문, 계정 상태, 정책 버전 | 실행에 필요한 구조화 입력 |
| constraints | 환불 확정 금지, 정책 근거 필수 | 금지 사항과 안전 경계 |
| tools | search_policy, lookup_order | 허용된 capability |
| output schema | 분류, 답변 초안, 근거 목록 | downstream이 바로 쓸 수 있는 형태 |
| escalation rule | 정책 불일치 시 human handoff | 실패 처리 기준 |
예시: agent 계약 스키마
type SupportResolution = {
classification: 'faq' | 'billing' | 'refund' | 'escalate'
answerDraft: string
evidence: Array<{ source: string; quote: string }>
confidence: number
nextAction: 'respond' | 'request-human-review'
}
type SupportAgentInput = {
userMessage: string
orderId?: string
locale: 'ko' | 'en'
policyVersion: string
}이 수준으로 계약을 정의하면 orchestrator는 모델 출력이 아니라 시스템 상태 전이를 기준으로 다음 동작을 정합니다.
프롬프트와 tool의 분리
프롬프트는 "어떻게 판단할 것인가"를, tool은 "무엇을 실행할 수 있는가"를 정의합니다. 둘이 섞이면 테스트하기도 재사용하기도 어려워집니다.
| 나쁜 예 | 왜 문제인가 | 더 나은 방식 |
|---|---|---|
| 프롬프트 안에 API 파라미터 규칙을 장문으로 설명 | 계약이 코드 밖에 흩어짐 | tool schema로 이동 |
| 프롬프트가 data retrieval 세부를 모두 지시 | model이 retrieval 경로까지 떠맡음 | retrieval tool과 정책 분리 |
| 도메인 지식과 행동 정책이 하나의 system prompt에 섞임 | 변경 영향이 큼 | prompt 레이어 분리 |
모델 선택 전략
| agent 유형 | 권장 모델 특성 | 이유 |
|---|---|---|
| 라우터/분류기 | 빠르고 저렴한 모델 | 대량 처리와 짧은 출력 |
| 리서처/플래너 | 긴 컨텍스트와 추론 안정성 | 탐색과 계획 품질 중요 |
| 실행 agent | tool calling 안정성 | 외부 시스템 조작 신뢰성 중요 |
| evaluator | 일관성과 structured output | pass/fail 기준 유지 필요 |
모델은 "책임" 뒤에 붙는 선택지입니다. agent 경계가 불분명한 채로 모델만 바꿔서는 품질 문제가 풀리지 않습니다.
사람 승인 경계 설계
agent 계약에는 escalation rule을 넣습니다. 되돌리기 어려운 작업, 규제 리스크가 큰 작업, 모델 confidence만으로 정당화하기 어려운 작업에는 human gate를 둡니다.
Handoff의 상세 설계는 에이전트 간 통신 챕터를 참조하세요.
흔한 실패 모드
| 실패 모드 | 원인 | 예방책 |
|---|---|---|
| 만능 agent화 | 책임이 너무 넓음 | capability가 아니라 결과물 기준으로 분리 |
| handoff 후 정보 손실 | 입력 계약이 약함 | goal, constraints, evidence를 구조화 전달 |
| tool 남용 | 모든 tool을 한 agent에 제공 | toolbox를 capability 단위로 분리 |
| 모델 교체 시 품질 붕괴 | 프롬프트가 모델 특성에 과적합 | output schema와 eval 세트를 고정 |
에이전트 설계 템플릿
### Agent Name
- Goal:
- Inputs:
- Allowed Tools:
- Output Schema:
- Escalation Rule:
- Observability Fields:
- Eval Dataset:문서를 이렇게 남겨두면 새 agent를 추가할 때도 "왜 존재하는가"를 빠르게 판단합니다.
ADR 스타일 결론
Decision
agent는 역할명이 아니라 책임 경계로 설계합니다. 각 agent는 좁은 목표, 제한된 tool, 구조화된 입력과 출력을 갖고, 사람 승인과 실패 처리 규칙을 계약에 담습니다.
실무 체크리스트
- 이 agent의 목표를 한 문장으로 설명할 수 있는가
- 입력과 출력이 구조화되어 있는가
- 허용된 tool이 최소 권한 원칙을 따르는가
- 실패 시 human handoff 기준이 있는가
- 모델 교체 후에도 유지되는 eval 세트가 있는가