# CAT.AI 설정·연동에서 파악된 문제점

> Green AI ① (CAT.AI 기반) PoC 구축 과정 (2026-07-21 ~ 2026-07-26) 정리.  
> 대상: catai.cc / XI Multi-AI Agent / DocStore / GreenAI-JCredit

## A. 문서·매뉴얼 갭

| # | 문제 | 영향 | 상태 |
|---|---|---|---|
| A-1 | 기초편·실전편은 **Classic Chatbot** 중심. XI Function 반환값 설정 설명이 없음 | Function→Agent로 `_result` 전달을 추측으로 구현하다 장기 난항 | 벤더 샘플 Bot + 회답으로 해소 |
| A-2 | 기초편 원문: 「XIは Classic Chatbotとは別データ」 | XI를 구 챗봇 매뉴얼로 유추하면 오작동 | 인지 완료 |
| A-3 | OpenAI Compatible / OpenRouter 공식 설정 예제가 부족 | BYO LLM 시행착오 | 벤더 추가 문의 권장 |

## B. Function / RAG 반환값 (핵심 블로커였음)

| # | 문제 | 증상 | 해결 |
|---|---|---|---|
| B-1 | `query` / `context.query` / `${...}` 등 잘못된 변수 표기 | `query is not defined`, `input: "{}"`, `No Result` | 검색 내용 = **`args.query`** |
| B-2 | `_result`를 Function 밖 Output에서 직접 참조 | `_result is not defined` | DOC Search **변수 설정**에 스코프 접두사 저장 |
| B-3 | Output에 `${JSON.stringify(context.docs)}` (JS 템플릿) | 문자 그대로 출력 / 파싱 실패 | Handlebars **`{{agent.func_result}}`** |
| B-4 | 변수 키를 `docs`만 사용 | Agent 스코프에서 안 보임 | 키 = **`agent.func_result`** |
| B-5 | Function 반환을 AI 자동생성에 맡김 | `content: "No Result"`, MiniMax 빈 content 연동 | 검색결과는 변수로 넘기고, Output(stream) description에 Handlebars |

### 벤더 확정 패턴 (샘플 Bot 기준)

```
DOC Search 변수설정:
  key:   agent.func_result
  value: _result ? JSON.stringify(_result) : '情報がありません'

Output (formatter / stream) 説明:
  検索結果：{{agent.func_result}}

Task 순서:
  Function(docstore_search) → Output(result) → Finish(終了)
```

스코프: `bot.` / `agent.` / `task.` / `args.`

## C. LLM 호환성

| # | 문제 | 증상 | 대응 |
|---|---|---|---|
| C-1 | OpenRouter SSE 주석 `: OPENROUTER PROCESSING` | `[toml_parser] invalid json` | OpenRouter는 XI 파서와 비호환에 가깝음. **공식 OpenAI 권장** |
| C-2 | MiniMax 세션 시작 빈 메시지 | `chat content is empty (2013)` | 채팅만 열면 실패할 수 있음. 즉시 질문 입력 |
| C-3 | MiniMax-M3 (추론형) + XI tool protocol | `Answer must start /content or /tool call` | Agent tool_parser와 불일치. 추론 모델 비권장 |
| C-4 | 모델명 미설정 / Description에만 기입 | `model: undefined` | Bot·Agent **モデル欄**에 명시 (예: `gpt-4.1`) |
| C-5 | Endpoint를 `/v1`만 지정 | HTML/오류 | OpenAI Compatible는 `.../v1/chat/completions` |

**PoC 성공 조합:** Type `openai` + 공식 OpenAI 키 + 모델 `gpt-5.4` / `gpt-4.1` 계열.

## D. 런타임·운영

| # | 문제 | 증상 | 비고 |
|---|---|---|---|
| D-1 | `function docstore_search not found` | Task에 Function이 보이는데 런타임 미등록 | 재저장·새 세션. 구조 깨짐 시 Function 재생성 |
| D-2 | Same Task called consecutively | 검색 0건 시 Agent가 Task 재호출 → 루프 가드 | 검색·반환 정상화로 해소 |
| D-3 | DocStore/XI 화면이 자동화 브라우저에서 빈 화면 | Playwright 검증 한계 | 수동 콘솔 확인 필요 |
| D-4 | IAM API Key ≠ DocStore 내부 API | 내부 `/docstore/api` 401 | IAM 키는 Open API용. 임베딩/LLM 키와 별개 |
| D-5 | 에러 후 UI 스피너 지속 | 사용자는 “느린지/멈춘지” 구분 불가 | Log에 red LLMCALL이면 실패로 판단, 새 세션 |

## E. 제품 방침 (Slack) vs 데모 레포

| # | 내용 |
|---|---|
| E-1 | Slack: **①은 CAT.AI**, **② AgreenAI는 스크래치** |
| E-2 | `greenai-demos`의 `open-inno/`는 스크래치 목업, `open-inno-catai/`가 CAT.AI 목업 |
| E-3 | 본 레포(`nt-greenai-catai`)는 CAT.AI **실봇 iframe 연결** + 문서 정리 |
| E-4 | 목업 검색·시나리오 채팅 제거. UI는 `/live/` `/docstore/` `/system/` 경로 라우팅 |

## F. 남은 과제

1. 커스텀 UI ↔ Bot Runtime API (헤드리스) 정식 연동 스펙 확정 (현재는 iframe)
2. DocStore Open API 베이스 URL·인증 헤더 확보 후, 브라우저/프록시 직접 검색 연동
3. OpenRouter 등 외부 LLM의 XI 스트리밍 호환을 벤더에 공식 확인
4. Slack 잔여 URL(AWD 웹·그린카본 자료) DocStore 보강 여부 결정
5. Coolify API 토큰 갱신 후 GUI 앱 등록으로 수동 Docker 배포 이관

## 참고 파일 (워크스페이스)

- 벤더 회답 PDF: `cat_ai_manual/CAT_AI回答まとめ_XI_Function戻り値設定_20260724.pdf`
- 샘플 Bot JSON: `cat_ai_manual/[PoC]GenAI_bot_【Partner】SampleBot_...json`
- 파악 현황: `greenai_project/99_참고자료/CATAI_파악현황.md`