| name | agent-harness-construction |
| description | AI 에이전트의 액션 스페이스, 도구 정의, 관측(Observation) 포맷을 설계·최적화해 작업 완수율을 높일 때 사용한다. |
| origin | ECC |
Agent Harness Construction
에이전트가 어떻게 계획하고, 도구를 호출하고, 오류에서 복구하고, 완료에 수렴하는지를 개선할 때 이 스킬을 사용한다.
핵심 모델
에이전트 출력 품질은 다음 네 요소에 의해 제약된다:
- 액션 스페이스 품질
- 관측(Observation) 품질
- 복구(Recovery) 품질
- 컨텍스트 예산 품질
액션 스페이스 설계
- 안정적이고 명시적인 도구 이름을 사용한다.
- 입력은 스키마 우선으로, 좁게 정의한다.
- 결정적인 출력 형태를 반환한다.
- 분리가 불가능한 경우가 아니라면 만능형(catch-all) 도구를 피한다.
입자도(Granularity) 규칙
- 고위험 작업(배포, 마이그레이션, 권한 변경)에는 마이크로 도구를 사용한다.
- 일반적인 편집·읽기·검색 루프에는 중간 입자도 도구를 사용한다.
- 왕복(round-trip) 비용이 지배적인 비용일 때만 매크로 도구를 사용한다.
관측(Observation) 설계
모든 도구 응답에는 다음을 포함해야 한다:
status: success|warning|error
summary: 한 줄 결과 요약
next_actions: 실행 가능한 후속 조치
artifacts: 파일 경로 / ID
오류 복구 계약(Contract)
모든 오류 경로마다 다음을 포함한다:
- 근본 원인 힌트
- 안전한 재시도 지침
- 명시적 중단 조건
컨텍스트 예산 관리
- 시스템 프롬프트는 최소한·불변으로 유지한다.
- 큰 가이드는 스킬로 분리해 필요할 때만 로드한다.
- 긴 문서를 인라인으로 넣기보다 파일 참조를 우선한다.
- 임의의 토큰 임계치가 아니라 작업 단계 경계에서 컴팩션한다.
아키텍처 패턴 가이드
- ReAct: 경로가 불확실한 탐색적 작업에 적합.
- Function-calling: 구조화된 결정적 흐름에 적합.
- 하이브리드(권장): ReAct 기반 계획 + 타입화된 도구 실행.
벤치마킹
다음 지표를 추적한다:
- 작업 완수율(completion rate)
- 작업당 재시도 수
- pass@1, pass@3
- 성공 작업당 비용
안티패턴
- 의미가 겹치는 도구가 너무 많은 경우.
- 복구 힌트가 없는 불투명한 도구 출력.
- 후속 조치 없이 오류만 내뱉는 출력.
- 관련 없는 참조로 컨텍스트를 과부하시키는 경우.