agent-harness-construction

Agent Harness Construction

에이전트의 계획 수립, 도구 호출, 오류 복구 및 작업 완료 능력을 개선할 때 이 스킬을 사용하세요.

핵심 모델

에이전트 출력 품질은 다음 요소에 의해 제한됩니다:

1. 액션 공간 품질 (Action space quality)
2. 관찰 품질 (Observation quality)
3. 복구 품질 (Recovery quality)
4. 컨텍스트 예산 품질 (Context budget quality)

액션 공간 설계

1. 안정적이고 명확한 도구 이름을 사용하세요.
2. 입력은 스키마 우선으로 유지하고 범위를 좁히세요.
3. 결정론적 출력 형태를 반환하세요.
4. 격리가 불가능하지 않은 한 포괄적 도구(catch-all)를 피하세요.

세분화 규칙

• 위험도가 높은 작업(배포, 마이그레이션, 권한)에는 마이크로 도구를 사용하세요.
• 일반적인 편집/읽기/검색 루프에는 중간 도구를 사용하세요.
• 왕복 오버헤드가 주요 비용일 때만 매크로 도구를 사용하세요.

관찰 설계

모든 도구 응답에는 다음을 포함해야 합니다:

• status: success|warning|error
• summary: 한 줄 결과
• next_actions: 실행 가능한 후속 조치
• artifacts: 파일 경로 / ID

오류 복구 계약

모든 오류 경로에 대해 다음을 포함하세요:

• 근본 원인 힌트
• 안전한 재시도 지침
• 명시적 중지 조건

컨텍스트 예산 관리

1. 시스템 프롬프트는 최소화하고 변경하지 않도록 유지하세요.
2. 긴 지침은 필요 시 로드되는 스킬로 옮기세요.
3. 긴 문서를 인라인으로 포함하는 대신 파일 참조를 선호하세요.
4. 임의의 토큰 임계값이 아닌 단계 경계에서 압축하세요.

아키텍처 패턴 가이드

• ReAct: 경로가 불확실한 탐색적 작업에 가장 적합합니다.
• 함수 호출: 구조화된 결정론적 흐름에 가장 적합합니다.
• 하이브리드 (권장): ReAct 계획 수립 + 타입화된 도구 실행.

벤치마킹

추적할 항목:

• 완료율
• 작업당 재시도 횟수
• pass@1 및 pass@3
• 성공적인 작업당 비용

안티 패턴

• 의미가 중복되는 너무 많은 도구.
• 복구 힌트가 없는 불투명한 도구 출력.
• 다음 단계 없이 오류만 출력.
• 관련 없는 참조로 컨텍스트 과부하.