Lab 04: 문서로 답한다

에이전트가 근거 있는 답을 하려면 무엇이 갖춰져야 하고, 근거가 없을 때는 무엇을 해야 하는가?

지정한 문서를 Knowledge Library에 등록하고, 같은 질문이 등록 전과 후에 어떻게 달라지는지 봅니다. 그리고 문서에 없는 것을 물었을 때 에이전트가 무엇을 하는지 확인합니다 — 이 실습에서 가장 중요한 장면입니다.

• 지정 폴더를 Knowledge 소스로 등록하고 수집 과정을 관찰합니다.
• 수집이 만드는 것들(items·entities·relations·embeddings)을 확인합니다.
• 검색 도구가 온디맨드로 로드되는 것을 관찰합니다.
• 답변의 인용을 원문 문서와 대조합니다.
• 검색이 유사하지만 답이 아닌 문서를 돌려줄 때의 처리를 관찰합니다.

이 Lab의 fixture는 클론한 레포에 미리 들어 있습니다. 다음 트리에서 파일 위치와 역할을 확인합니다.

labs/04-knowledge-rag/
├── data/
│   ├── product-catalog.json       ← standard / personalized 제품 2종
│   └── support-policy.md          ← TRAINING-EXCHANGE-04 교환 정책
└── questions/
    └── customer-question.md       ← 확장 질문에서 사용하는 고객 사례

• product-catalog.json에는 standard 제품과 personalized 제품의 코드·분류·구성품이 들어 있습니다.
• support-policy.md에는 TRAINING-EXCHANGE-04 정책 ID와 교환 조건, 추가 정보 요청 조건이 들어 있습니다.
• customer-question.md에는 제품 코드·구매일·손상 상황과 아직 제공되지 않은 정보가 들어 있습니다.

두 문서에 배송 기간 정책은 없습니다. 일부러 없습니다.

공통 준비를 먼저 수행합니다.

□ 새 세션을 만들었다
□ 하단 표시줄이  default · nxt-kirocrew-hands-on · main
□ 실행 모드가  Normal

이 실습만의 조건입니다.

• Knowledge 화면 하단 카운터가 0 items여야 합니다. 이전 실습의 소스가 남아 있으면 정리부터 합니다.
• 소스 목록에 Artifacts(artifact:// · manual)가 보이는 것은 정상입니다. 시스템 기본 소스이며 이 실습과 무관합니다.

---

Knowledge를 엽니다. 하단 카운터를 읽습니다.

0 items · 0 entities · 0 relations · 1 sources · embeddings (0)

1 sources가 무엇인지 Sources 탭에서 확인해 둡니다. 시스템 기본 소스인 Artifacts가 보입니다.

이 상태에서 검색하면 무엇이 나올지 뒤에서 확인하게 됩니다. 빈 것을 먼저 봐 두어야 “결과 없음”이 고장이 아니라는 것을 압니다.

Sources 탭 → + Add Source를 누릅니다.

읽어 둘 것이 세 가지 있습니다.

항목	의미
Local File / Local Folder	파일 업로드 또는 폴더 감시
Namespace	지식을 구획으로 나누는 이름. Type new to create
Ignore patterns	수집에서 제외할 패턴 (예: .trash/*)

패널 하단의 지원 형식 안내도 읽어 둡니다.

• Markdown·텍스트·코드·HTML·JSON·YAML·CSV·DOCX·PDF를 지원합니다.
• 파일당 최대 크기는 50 MB입니다.
• 확장자가 없는 파일(예: README)은 파일 선택기에 나타나지 않으므로 드래그 앤 드롭으로만 올릴 수 있습니다.

Local Folder를 선택하고 입력합니다.

필드	값
Name	NXT 지원 정책과 제품 카탈로그
Folder path (macOS)	/Users/<사용자명>/Desktop/work/nxt-kirocrew-hands-on/labs/04-knowledge-rag/data
Folder path (Windows)	C:\Users\<사용자명>\Desktop\work\nxt-kirocrew-hands-on\labs\04-knowledge-rag\data

Windows에서 역슬래시 경로가 입력되지 않으면 Browse... 버튼으로 폴더를 선택합니다.

폴더 모드의 안내도 확인합니다.

• 하위 폴더까지 재귀적으로 감시합니다. Include subdirectories는 기본으로 켜져 있습니다.
• 소스당 최대 5,000개 파일을 감시합니다.

Add Folder를 누르면 등록 전에 확인이 나옵니다.

.../nxt-kirocrew-hands-on/labs/04-knowledge-rag/data — 2 supported files found
This folder will be watched continuously.
New files added here will be auto-ingested on the next scan cycle (~5 min).

번역: nxt-kirocrew-hands-on/labs/04-knowledge-rag/data에서 지원되는 파일 2개를 찾았습니다. 이 폴더는 계속 감시되며, 새로 추가한 파일은 다음 스캔 주기에 자동으로 수집됩니다.

등록은 일회성 업로드가 아니라 감시입니다. 폴더에 파일을 추가하면 다음 주기에 자동 수집됩니다. Start Scanning을 누릅니다.

소스 행을 펼치면 파일별 진행률이 보입니다.

2/2 (100%)가 되고 상태가 synced로 바뀌면 수집은 끝입니다.

그런데 상단에 배너가 하나 떠 있습니다.

Embedding engine ready — knowledge items need embedding.  Generate now

번역: 임베딩 엔진이 준비되었습니다 — 지식 항목에 임베딩이 필요합니다. 지금 생성합니다.

수집과 임베딩은 별개 단계입니다. 문서는 들어왔지만 검색용 임베딩은 아직 없습니다. 배너의 Generate now를 눌러 임베딩을 생성합니다. 잠시 후 배너가 준비 완료 신호로 바뀝니다.

Smart Search active · 2/2 embedded (100%)

번역: 스마트 검색이 활성화되었습니다 — 2개 중 2개가 임베딩되었습니다(100%).

List View로 이동합니다.

단순 저장이 아닙니다. 문서마다 영어 요약이 생성되고, 타입 태그(policy, external reference)가 붙고, 엔티티와 관계가 추출되고, 임베딩이 만들어졌습니다. 하단 카운터로 확인합니다.

0 items · 0 entities · 0 relations · embeddings (0)     ← 등록 전
2 items · 6 entities · 4 relations · embeddings (2)     ← 등록 후

엔티티·관계 수는 실행마다 조금 다를 수 있습니다. 추출은 결정적이지 않습니다.

Graph View 탭에서 추출된 것의 정체가 보입니다 — 문서 속 개념들이 노드가 되고 관계가 선이 됐습니다.

Standard Products ─ part_of ─ TRAINING-EXCHANGE-04 ─ part_of ─ Personalized Products
NXT ─ owns ─ NXT Travel Mug · NXT Engraved Bottle

먼저 도구 없이 물어보면 — 이 길은 검색이 아닙니다

새 세션을 만들고 프로젝트 폴더를 연결한 뒤, 도구 언급 없이 자연어로만 물어봅니다.

NXT 교환 정책에서 개인화 제품의 교환 가능 조건을 알려 줘.

진행 단계를 봅니다.

도구를 언급하지 않았을 때 무엇을 하는지는 모델 재량입니다 — 파일을 직접 찾아 읽을 수도, 스스로 검색 도구를 로드할 수도 있습니다. 아래는 파일을 직접 읽은 실행의 기록입니다. 여러분의 실행에서 처음부터 검색 도구가 로드됐다면 이 경로 자체가 재현되지 않은 것이니, 그 관찰(도구가 필요할 때 로드된다는 것)을 그대로 챙기고 다음 단계로 넘어갑니다.

Finding labs/04-knowledge-rag/**/* in nxt-kirocrew-hands-on
Searching for '개인화|교환' in support-policy.md
Reading support-policy.md:1

이 실행에서는 지식 라이브러리를 건드리지도 않았습니다. 연결된 프로젝트 폴더에서 파일을 찾아 직접 읽은 것입니다. 답의 내용은 맞고 출처도 파일 경로로 붙습니다. 그러나 이것은 검색이 아니라 읽기입니다.

왜 구분이 중요한가 —

• 폴더 연결이 없으면 이 길은 없습니다. 다른 입구에서는 파일을 읽을 수 없습니다. 등록된 지식은 어디서든 검색됩니다.
• 이 길은 등록되지 않은 파일도 근거로 씁니다. 폴더에 있기만 하면 읽히므로, 관리·검증한 지식만 쓰게 하는 통제가 사라집니다.
• 3단계에서 만든 요약·임베딩·구획은 전혀 쓰이지 않았습니다.

등록된 지식을 쓰게 하려면 도구를 명시합니다. 같은 세션에 이어서 입력합니다.

local_knowledge_search 도구로 NXT 교환 정책을 검색해서,
개인화 제품의 교환 가능 조건을 근거 문서와 함께 알려 줘.

관찰 1 — 도구가 도착하는 순간

이번에는 파일 탐색 대신 검색 도구를 로드합니다.

Load the knowledge search tool to look up NXT exchange policy.
Search NXT exchange policy for personalized product exchange conditions.

번역: NXT 교환 정책을 찾기 위해 지식 검색 도구를 로드합니다. 개인화 제품의 교환 조건에 대해 NXT 교환 정책을 검색합니다.

검색 도구는 항상 실려 있는 것이 아니라 필요할 때 로드됩니다. Lab 2의 스킬 로드와 같은 원리가 도구에도 적용됩니다(Tool Search).

관찰 2 — 근거가 붙은 답

[NXT] 개인화 제품(personalized)의 교환 가능 조건을 근거 문서와 함께 정리했습니다.

개인화 제품 교환 조건 (정책 ID: TRAINING-EXCHANGE-04)
- 단순 변심 교환: 불가
- 제조 오류 또는 배송 파손: 구매 후 14일 이내, 사람 검토 필요
- 공통 단서: 구매일·구매 증빙·제품 코드·손상 상태가 확인되지 않으면 자동 승인하지 않고 추가 정보를 요청함

근거 문서
- 교환 정책 원문: .../labs/04-knowledge-rag/data/support-policy.md (「개인화 제품」 및 「판단 불가」 절)
- 제품 분류 참고: .../data/product-catalog.json — NXT-RAG-BETA 가 return_class: "personalized" 로 분류됨

번역: 개인화 제품의 교환 가능 조건을 근거 문서와 함께 정리했습니다. 교환 정책 원문과 제품 분류 참고 문서를 근거로 사용했습니다.

관찰 3 — 인용을 원문과 대조한다

에이전트의 답을 그대로 믿지 않습니다. labs/04-knowledge-rag/data/support-policy.md를 직접 열어 “개인화 제품” 섹션과 대조합니다.

• 정책 ID(TRAINING-EXCHANGE-04)가 원문에 있는가?
• 답변에 원문에 없는 조건이 섞이지 않았는가?
• 두 근거 문서의 역할이 답변에서 정확히 구분되었는가?

인용이 있다는 것과 인용이 정확하다는 것은 다릅니다. 대조가 검증입니다.

같은 세션에 이어서, 이번에는 방어선 없는 프롬프트를 그대로 입력합니다.

같은 방식으로 배송 기간 정책도 검색해서 알려 줘.

먼저 예측해 보세요 — 검색은 무엇을 돌려주고, 에이전트는 무엇을 할까요?

먼저 도구 호출의 Output 탭을 열어 봅니다 — 검색이 실제로 무엇을 돌려줬는지 눈으로 확인할 수 있습니다.

검색은 빈손으로 돌아오지 않았습니다. 라이브러리에 문서가 두 건뿐이므로, 배송 기간과 무관한 그 두 건이 그대로 돌아왔습니다. 이 원재료를 에이전트가 어떻게 다루는지가 관찰 대상입니다. (화면 끝에 건방진 인사가 보인다면 Lab 3 추가 미션의 규칙이 아직 살아 있는 것입니다 — always-on은 이렇게 계속 따라다닙니다.)

[NXT] 배송 기간 정책을 지식 라이브러리에서 검색했지만, 관련 문서를 찾지 못했습니다.
검색으로 반환된 문서는 두 건뿐이며, 둘 다 배송 소요 기간에 대한 내용은 없습니다.

- .../data/support-policy.md — 교환 정책(표준/개인화/판단 불가)만 다룸.
  "배송 파손" 언급은 있으나 배송 기간 규정은 없음
- .../data/product-catalog.json — 제품 분류·구성품 정보만 있음

배송 기간(예: 발송·도착 소요일) 정책은 지식 라이브러리에 존재하지 않습니다.
추측으로 만들지 않고 없음으로 보고합니다.

검증: 확인 1건(배송 기간 정책 문서 부재) / 미확인 0건

이 실습의 핵심 결론입니다. 검색의 실패 모드는 “결과 없음”만이 아닙니다. 유사하지만 답이 아닌 문서가 돌아오는 것이 더 위험합니다. “배송 중 파손”은 질문과 단어가 겹치지만 배송 기간 조항이 아닙니다. 에이전트는 그 차이를 짚고 추측 없이 없음으로 보고했습니다.

방어선 없이도 거부했다 — 그런데 그것은 보장이 아닙니다

이번 요청에는 “없으면 없다고 말해, 추측으로 답을 만들지 마” 같은 방어선이 없었습니다. 그런데도 추측하지 않았습니다 — Steering의 검증 요약 규칙(Lab 3)이 근거 표시를 강제하고 있었고, 모델도 신중하게 동작했습니다.

그러나 이 거부는 운과 설정에 기댄 것이지 보장이 아닙니다. 모델이 달라지면, Steering이 없으면, 질문이 더 그럴듯하면 유사 문서를 근거로 답이 만들어질 수 있습니다. 그래서 실무에서는 거부를 운에 맡기지 않고 규칙으로 만듭니다 —

검색 결과가 없으면 없다고 말하고, 추측으로 답을 만들지 마.

이 한 줄을 어디에 두면 매번 쓰지 않아도 되는지 — 6단계 토론의 마지막 질문입니다.

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

우리 팀 문서 중 Knowledge에 넣을 것과 넣지 말아야 할 것은?

생각해 볼 답

넣을 것: 자주 참조되고, 갱신 주기가 명확하고, 내용의 정확성을 책임지는 사람이 있는 문서 — 정책, 절차서, 카탈로그. 넣지 말 것: 개인정보·민감 정보(등록되면 모든 세션의 검색 대상이 됩니다), 금방 낡는 문서(낡은 채로 근거가 됩니다), 아무도 관리하지 않는 문서. 판별 질문은 “이 문서가 틀렸을 때 누가 알아차리는가?”입니다. 답이 없으면 넣지 않습니다.

Namespace는 무엇 기준으로 나누는 게 좋은가?

생각해 볼 답

정답은 조직마다 다르지만, 유용한 기준은 신뢰 수준과 갱신 주체입니다 — 공식 정책(검증됨)과 팀 메모(미검증)가 한 구획에 섞이면 검색 결과의 신뢰 수준을 구분할 수 없게 됩니다. 팀·제품 기준 구획은 검색 범위를 좁히는 데 유용합니다. 검색이 구획을 넘는지 실험하면 설계 기준이 더 분명해집니다.

감시 폴더에 누군가 잘못된 문서를 넣으면 무슨 일이 생기는가?

생각해 볼 답

다음 스캔 주기(~5분)에 자동 수집되어 그날부터 에이전트의 근거가 됩니다. 등록은 감시라는 것의 어두운 면입니다 — 등록된 문서는 틀려도 근거가 됩니다. 발견 방법은 답변의 인용을 원문과 대조하는 습관과 List View에서 낯선 항목이 생겼는지 정기적으로 확인하는 것입니다. 감시 폴더의 쓰기 권한을 관리하는 것이 근본 대책입니다.

“검색 결과가 없으면 없다고 말해”를 프롬프트마다 쓰는 대신 어디에 두면 되는가?

생각해 볼 답

항상 지킬 규칙이므로 Steering(Lab 3)이 제자리입니다 — nxt-response-style.md에 한 줄 추가하면 모든 세션에 적용됩니다. 검색을 포함한 점검 절차 전체를 표준화하려면 스킬(Lab 2)에 넣어 함께 로드할 수도 있습니다. 절차는 스킬로, 규칙은 Steering으로 — Lab 2와 Lab 3의 결론을 조합합니다.

정리는 삭제가 아니라 남길 것을 정하는 일입니다. 지식 라이브러리는 일회성 연습 예제가 아니라 쌓아 나가는 자산입니다 — 등록한 정책은 다음 랩들과 연습에서도 근거로 계속 쓰입니다. 소스를 남깁니다.

단, 남기는 것은 결정이지 방치가 아닙니다. 두 가지를 알고 남깁니다.

• 감시는 계속됩니다. 폴더에 파일이 추가되면 다음 주기에 자동 수집됩니다 — 무엇이 들어가는 폴더인지 아는 상태로 남깁니다.
• 등록된 문서는 계속 근거가 됩니다. 내용이 낡으면 낡은 근거가 됩니다 — 6단계 토론의 “틀렸을 때 누가 알아차리는가”가 남기는 조건입니다.

완전 정리 — 과정을 여기서 끝내는 경우에만

1. Knowledge → Sources에서 실습 소스의 ×를 누릅니다. 확인 대화상자는 브라우저 기본 창이므로 화면에서 직접 누릅니다.
2. 하단 카운터가 0 items로 돌아왔는지 확인합니다. (Artifacts 기본 소스는 남습니다.)

도입 — 4단계의 도구를 밖에서 꽂기

4단계에서 Loading tool: local_knowledge_search를 봤습니다. 그 도구는 시스템이 내장한 것이었습니다. 그렇다면 없는 도구가 필요하면 어떻게 할까요?

Agent Capabilities → Connections → MCP Servers 탭을 엽니다. 지금까지 에이전트가 쓰던 도구들의 출처가 여기 있습니다 — kirocrew-core(63 tools), kirocrew-cron(8 tools) 같은 서버들이 Online 상태로 돌고 있고(도구 개수는 버전에 따라 다릅니다), 도구는 전부 이런 MCP 서버를 통해 에이전트에 연결됩니다. MCP(Model Context Protocol)는 에이전트와 도구를 연결하는 공개 표준이라, 세상에 공개된 MCP 서버는 무엇이든 같은 방식으로 꽂을 수 있습니다.

세계 시각을 조회하는 공식 레퍼런스 서버 mcp-server-time을 꽂아 봅니다.

이 실습은 uv가 설치되어 있어야 합니다 — 터미널에서 uvx --version으로 확인합니다. Lab 0에서 이미 설치됐어야 하지만, 없으면 macOS는 brew install uv, Windows는 winget install --id astral-sh.uv -e로 설치합니다.

서버를 등록한다

{} Add Custom을 누르면 JSON 입력 폼이 열립니다. 안내문이 핵심을 말해 줍니다 — 아무 MCP 서버 README의 mcpServers 블록을 그대로 붙여 넣으면 됩니다. 아래를 복사해 붙여 넣습니다.

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["--with", "mcp<2", "mcp-server-time"]
    }
  }
}

폼 아래 WILL ADD 미리보기로 무엇이 등록될지 확인하고, Enable immediately를 체크한 뒤 Add를 누릅니다.

번역: 지금 추가할 서버 목록을 미리 보여 줍니다. 즉시 활성화를 선택한 뒤 추가합니다.

목록에 time 서버가 생기면 우측 상단의 새로고침 버튼으로 상태를 확인합니다. Online이 되고 도구 수를 펼치면 두 개가 보입니다.

time  Online  2 tools
  · get_current_time
  · convert_time

번역: time 서버가 온라인 상태이며 두 도구를 제공합니다. get_current_time은 현재 시각을, convert_time은 시간대를 변환합니다.

Unknown이나 Error가 나오면 — 상태가 Error로 바뀌길 기다려 stderr 메시지를 읽습니다. 원인이 화면에 그대로 있습니다. 서버 커맨드를 터미널에서 직접 실행해 보는 것도 같은 답을 줍니다. 위 JSON의 "--with", "mcp<2"처럼 MCP SDK 버전을 고정해야 기동하는 서버도 있습니다. 행의 {} 버튼으로 JSON을 언제든 고칠 수 있습니다.

에이전트에 연결한다

서버가 Online이어도 이 버전에서는 한 단계가 더 남았습니다. time 행의 KiroCrew 칩을 한 번 클릭해 껐다가, 다시 클릭해 켭니다. 그리고 Apply & Restart를 누릅니다.

왜 이런 동작이 필요할까요? “연결됨”이 계층마다 따로 있기 때문입니다.

계층	의미
서버 기동 (Online)	프로세스가 뜨고 도구를 감지했다
에이전트 노출	세션의 도구 목록에 실제로 들어갔다
자동 승인	승인 카드 없이 호출된다

Online은 첫 번째 계층일 뿐입니다. 칩을 다시 켜는 순간 두 번째·세 번째가 연결되고, Apply & Restart가 세션에 반영합니다.

세션이 “그런 도구 없다”고 하면 — 위 단계를 건너뛴 것입니다. 이때 에이전트는 정직하게 사용 가능한 서버 목록을 말해 주고, 셸 명령으로 우회하려 듭니다. 도구가 없으면 다른 길을 찾는 것 — 4단계에서 본 그 습성입니다.

세션에서 확인한다

새 세션을 열고 물어봅니다.

현재 시간 관련 mcp 도구가 있어?

에이전트가 time::get_current_time, time::convert_time 두 도구를 정확히 소개합니다. 이어서 일을 시킵니다.

지금 파리와 런던의 시간을 알려줘

도구 로딩(Loading tool: time::get_current_time)과 단계별 호출을 거쳐 두 도시의 현재 시각이 서머타임 적용까지 정확하게 나옵니다. Output 탭을 열면 도구가 반환한 원시 데이터도 볼 수 있습니다 — 5단계에서 검색 도구에 했던 그 확인법 그대로입니다.

번역: Loading tool: time::get_current_time은 time::get_current_time 도구를 로드하는 중이라는 뜻입니다. Output 탭에서는 도구가 반환한 원시 결과를 확인할 수 있습니다.

그런데 도구를 명시하지 않으면

서버를 등록하기 전에 같은 질문을 던져 봤다면 어땠을까요. 아래는 등록 전에 물었던 기록입니다 — 이미 등록을 마친 지금은 재현할 수 없지만, 대비를 보기에는 기록으로 충분합니다.

에이전트는 도구 없이 시간대 지식으로 직접 계산해서 답합니다. 물어보면 “MCP 툴은 사용하지 않았습니다”라고 스스로 밝힙니다. 4단계의 결론이 여기서도 반복됩니다. 모델은 자기가 할 수 있는 일에는 도구를 쓰지 않습니다. 도구가 필수가 되는 것은 모델이 할 수 없는 일 — 실시간 데이터, 조직 내부 문서(이 랩의 지식 라이브러리), 외부 시스템 조작 — 일 때입니다.

두 번째 서버 — 모델이 못 하는 일을 시킨다

그렇다면 도구가 정말 필수인 서버를 하나 더 꽂아 봅니다. AWS 공식 문서를 검색·열람하는 aws-documentation-mcp-server입니다 — 문서는 계속 갱신되므로 모델의 지식만으로는 “지금 문서에 뭐라고 쓰여 있는지” 답할 수 없습니다.

같은 방법입니다. {} Add Custom에 붙여 넣고, Enable immediately 체크 → Add → 칩 재토글 → Apply & Restart를 누릅니다.

{
  "mcpServers": {
    "aws-docs": {
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"]
    }
  }
}

새 세션에서 물어봅니다 — “공식문서에 의거해서”가 핵심입니다. 이 조건이 모델의 기억 대신 도구를 강제합니다.

람다 함수의 제한 시간에 관한 내용을 공식문서에 의거해서 답변해줘

reasoning을 펼쳐 보면 이번엔 도구를 두 단계로 씁니다 — 먼저 문서를 검색하고(search_documentation), 찾은 페이지를 읽어(read_documentation) 정확한 수치를 가져옵니다. 4단계에서 배운 검색과 읽기의 구분이 외부 도구에서도 그대로 나타납니다.

답변에는 기본값 3초·최대 900초 같은 수치와 함께 출처 URL(docs.aws.amazon.com/lambda/.../configuration-timeout.html)이 달립니다. 5단계에서 했던 그 검증 — 인용을 원문과 대조하기 — 을 이번엔 실제 공식 문서 링크로 할 수 있습니다.

time 서버와 비교해 봅니다. 시간은 모델이 스스로 계산해 버렸지만, “지금 공식 문서의 내용”은 도구 없이는 근거를 만들 수 없습니다.

정리

time 서버는 연습 예제이므로 Uninstall로 제거해도 됩니다. 반면 aws-docs는 공식 문서를 확인하는 실무 자산이므로 남기는 쪽을 권합니다 — 7단계의 기준 그대로, 남긴다면 무엇이 언제 불리는지 아는 상태로 남깁니다.

• 등록 전 0 items와 Artifacts 기본 소스를 확인했습니다.
• 지원 형식·50 MB 제한·확장자 없는 파일의 드래그 앤 드롭 방식을 확인했습니다.
• 폴더의 재귀 감시와 소스당 5,000파일 제한을 확인했습니다.
• 폴더 등록 시 2 supported files found와 감시 안내를 읽었습니다.
• 수집 후 synced 상태에서 Generate now를 눌렀습니다.
• Smart Search active · 2/2 embedded (100%)를 확인했습니다.
• 카운터에서 entities·relations가 생긴 것과 Graph View의 노드·관계를 확인했습니다(숫자는 실행마다 다를 수 있습니다).
• Loading tool: local_knowledge_search를 관찰했습니다.
• 답변의 인용을 원문과 대조했습니다.
• 도구 없이 물으면 파일 직접 읽기로 새는 것을 관찰하고, 검색과 읽기를 구분했습니다.
• 없는 정보 질문에서 유사 문서가 반려되고 추측 없이 없음으로 보고되는 것을 확인했습니다.
• 지식 소스를 남기는 결정과 그 조건(감시 지속·근거 지속)을 확인했습니다.

증상	먼저 확인할 항목
수집이 0건	폴더 경로 오타, 지원 형식 여부
검색 도구를 안 씀	프롬프트에 도구 이름을 명시했는지
검색 결과가 이상하게 많음	이전 실습 소스가 남았는지 — 시작 조건의 0 items
없는 정보에 그럴듯한 답을 함	프롬프트에 “추측 금지”가 있었는지 — 없애고 재실행해 비교해 보세요
소스 제거 후에도 검색됨	카운터가 실제로 0으로 돌아왔는지, 세션이 새것인지

등록은 저장이 아니라 감시이고, 수집은 복사가 아니라 요약·추출·임베딩입니다.

검색 도구는 등록된 것만 봅니다. 등록되지 않은 문서는 없는 것과 같고, 등록된 문서는 틀려도 근거가 됩니다. 지식의 품질 책임은 등록하는 사람에게 있습니다.

가장 위험한 검색 결과는 빈 결과가 아니라 유사한 오답입니다. “없으면 없다고 말하라”는 지시가 그 방어선이고, 인용과 원문의 대조가 최종 검증입니다.

먼저 스스로 답해 본 뒤 접힌 답과 비교해 보세요.

대시보드 상단 검색창(Search knowledge...)의 결과와 세션 안 검색 결과는 같은가?

생각해 볼 답

같은 라이브러리를 보지만 쓰임이 다릅니다. 검색창은 사람이 항목을 직접 찾아보는 조회이고, 세션 검색은 에이전트가 답변 근거로 쓰기 위한 도구 호출입니다. 같은 질의를 양쪽에 넣어 비교하면, 에이전트 쪽은 검색 결과를 다시 해석해 답을 만들기 때문에 그 해석 단계도 검증 대상이라는 것을 알 수 있습니다.

문서를 수정하면 다음 스캔 주기에 items는 어떻게 변하는가? 직접 실험해 보세요.

생각해 볼 답

감시 중인 폴더이므로 다음 스캔 주기(~5분)에 다시 수집됩니다. 항목 수보다 중요한 것은 요약·엔티티·임베딩이 새 내용 기준으로 갱신되는지입니다. 임베딩 생성이 별도 단계였던 것을 기억하면, 수정 후 검색 결과가 언제부터 새 내용을 반영하는지도 확인할 수 있습니다.

Namespace를 나눴을 때 검색은 구획을 넘는가?

생각해 볼 답

새 Namespace로 소스를 하나 더 등록하고 검색 범위를 비교해 보세요. 구획을 넘는다면 Namespace는 분류일 뿐 격리가 아니고, 넘지 않는다면 검색 범위 설계가 곧 답변 범위 설계가 됩니다. 어느 쪽인지에 따라 Namespace를 팀·제품·신뢰 수준 중 무엇으로 나눌지 결정할 수 있습니다.

이 지식 검색과 웹 검색(web_search)의 신뢰 수준을 어떻게 구분해서 다뤄야 하는가?

생각해 볼 답

지식 검색은 우리가 등록하고 관리하는 문서를 대상으로 하므로 출처와 책임자가 있습니다. 웹 검색은 출처가 통제 밖에 있습니다. 정책·기준처럼 조직이 책임지는 답은 지식 검색으로, 최신 외부 정보는 웹 검색으로 다루고, 답변에 어느 쪽 근거인지 표시하게 하는 것이 안전합니다.

questions/customer-question.md의 고객 질문에 등록된 정책을 근거로 답하게 해 보세요. 고객이 제공하지 않은 정보(손상 사진 여부)를 에이전트가 어떻게 처리해야 하는가?

생각해 볼 답

정책에는 배송 파손 시 손상 사진 확인이 필요하지만 고객 질문에는 사진 제공 여부가 없습니다. 좋은 에이전트는 교환 가능 조건을 안내하되 사진 확인이 남았다는 것을 추가 확인 사항으로 분리해야 합니다. 단정해 버린다면 프롬프트나 스킬에 미확인 정보를 분류하는 절차가 빠진 것입니다.

클론한 저장소의 themes/program-office/는 방금 밟은 흐름을 대학 사업단 상황으로 다시 도는 테마 팩입니다. themes/program-office/README.md를 먼저 열고 Lab별 매핑 표와 파일 위치를 확인합니다. 실제 민감 데이터나 회사 자료는 넣지 말고, 공개 자료를 흉내 낸 가상의 문서와 질문으로 연습하세요.

Lab 4의 테마는 운영 지침 QA — 참가 자격·수료 기준을 인용해 답하기입니다. themes/program-office/policy/ 폴더의 가상 운영 지침을 Knowledge 소스로 등록하고 다음을 반복합니다.

1. 등록 전 빈 상태와 Artifacts 기본 소스를 확인합니다.
2. policy/ 폴더를 Local Folder로 등록하고, 재귀 감시·지원 형식·파일 수를 확인합니다.
3. 수집과 임베딩을 분리해 관찰하고, List View의 요약·타입 태그와 Graph View를 확인합니다.
4. 참가 자격과 수료 기준을 묻고, 답변의 인용을 원문과 대조합니다.
5. 지침에 없는 처리 기한이나 예외를 물어봅니다. 유사한 문장이 검색되어도 추측하지 않고 추가 확인 사항으로 분리하는지 확인합니다.

연습용으로 추가한 소스만 제거합니다 — 본 실습 소스는 7단계 기준대로 남깁니다. 시간이 남으면 같은 구조를 자기 업무의 소재로 바꾸어 보되, 실제 민감 데이터 대신 구조만 재현한 가상의 예시 파일을 사용하세요.