Agent Engine

Agent Engine은 사용자가 요청한 작업을 태스크 단위로 분해해 실행하고, 도메인 API·검색·툴 호출을 조합해 결과를 반환합니다.

구성 요소

• Task Planner
  • 사용자 입력에서 수행 단위를 나누고 실행 순서를 정함
• Tool Router
  • 내부 API, 검색, 문서 조회 중 필요한 툴을 선택
• Execution Worker
  • 실제 동작을 비동기로 수행하고 진행률/상태를 갱신
• Result Composer
  • 중간 응답과 최종 응답을 정리해 일관된 포맷으로 응답

실행 라이프사이클

1. 요청 수신: /api/agent/execute 에서 작업 단위 파라미터 수신
2. 검증: 인증, 권한, 리소스 제약, 입력 스키마 검증
3. 큐 적재: 작업 ID 발급 후 큐 또는 worker에 위임
4. 실행: 계획 생성 후 tool 호출
5. 상태 업데이트: queued -> running -> done/failed 전이
6. 완료 응답: 결과 저장 및 요약 반환

상태 값

• queued: 대기 중
• running: 실행 중
• succeeded: 정상 완료
• failed: 실패
• cancelled: 사용자 취소
• expired: 타임아웃으로 만료

Retry 정책(권장)

• 일시적 외부 API 실패는 지수 백오프 기반 재시도
• 멱등성이 보장되지 않는 동작은 재시도 제외
• 반복 실패 시 dead-letter 로그와 운영 알림을 남김

운영 팁

• 장기 작업은 polling보다는 webhook/이벤트 채널을 병행
• 로그에 traceId, jobId, userId를 포함해 추적성 강화
• Agent 응답 품질은 도구 정책, 컨텍스트 길이 제한, 검색 최신성에 민감하므로 테스트 데이터셋으로 정기 점검