51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# 문제 해결
|
|
|
|
## 텍스트만 답하고 리포트가 생성되지 않음
|
|
|
|
**원인**: 포털이 단일 조회만 실행했거나, MCP discovery 결과에 이전 결과 입력형 렌더러가 없다.
|
|
|
|
**확인**:
|
|
|
|
1. 포털 설정 endpoint가 `https://hmm-backoffice.cloud-handson.com/mcp`인지 확인한다.
|
|
2. `tools/list` 결과에 조회 도구와 `reportJson` 입력을 가진 HTML/리포트 렌더러가 모두 있는지 확인한다.
|
|
3. 포털 실행 상세에서 실행 방식이 `agent`, Agent 단계가 두 번인지 확인한다.
|
|
|
|
**해결**: endpoint와 허용 목록을 함께 갱신한 뒤 포털 서비스를 재기동한다. 렌더러 설명에는
|
|
`조회 결과 후속 처리`처럼 선행 결과를 받는다는 문구를 유지한다.
|
|
|
|
**재발 방지**: 새 업무 리포트 도구도 `reportJson`류 입력과 후속 처리 의도를 설명에 선언한다.
|
|
포털 코드에 특정 도구명을 추가하지 않는다.
|
|
|
|
## 렌더러가 입력 형식 오류를 반환함
|
|
|
|
**원인**: 조회 도구가 `items`/`results` 배열을 반환하지 않거나, 렌더러가 요구하는 payload 계약과
|
|
템플릿 계약이 다르다.
|
|
|
|
**확인**: 첫 Agent 단계의 응답에 행 배열이 있는지, 두 번째 단계 arguments에 `report`와 `rows`가
|
|
있는지 확인한다. 비밀값·Bearer token은 실행 상세에 남기지 않는다.
|
|
|
|
**해결**: 조회 도구는 구조화 행 배열을 반환하고, 렌더러 함수는 `report`와 `rows` 계약을 유지한다.
|
|
|
|
## 생성된 HTML이 화면에 표시되지 않음
|
|
|
|
**원인**: 렌더러 응답에 `html` 문자열이 없거나, HTML이 유효하지 않다.
|
|
|
|
**확인**: 두 번째 MCP 응답의 `response.html` 존재와 길이를 확인한다.
|
|
|
|
**해결**: DB 템플릿 활성 상태와 custom Agent Tool의 반환 형식을 확인한다. 포털은 유효한 `html`
|
|
또는 `rendered_html`만 sandboxed iframe으로 표시한다.
|
|
|
|
## 리포트는 생성됐지만 행이 0건임
|
|
|
|
**원인**: 렌더러 앞에서 실행된 데이터 조회 Tool이 0건을 반환했다. 렌더러는 없는 행을 만들거나
|
|
기본 샘플을 채우지 않는다.
|
|
|
|
**확인**: Agent 첫 단계의 결과 건수와 두 번째 단계 `reportJson.rows`를 비교한다. 둘 다 0건이면
|
|
HTML 생성 경로는 정상이다.
|
|
|
|
**해결**: 같은 사용자와 질문으로 데이터 조회 Tool만 별도 호출해 권한 범위와 조회 결과를
|
|
확인한다. HTML 템플릿, renderer 함수 또는 Agent 순차 실행 규칙은 변경하지 않는다.
|
|
|
|
**재발 방지**: HTML Tool 검증에는 별도의 합성 payload를 사용하고, 데이터 조회 검증과 판정을
|
|
분리한다.
|