배포하고 실행 기록으로 문제 찾기
완성한 에이전트를 저장·배포하고 미리보기와 채팅에서 도구 호출 및 액터 승인을 확인한 뒤 실행 기록으로 실패 단계를 찾습니다.
마지막 레슨에서는 지금까지 만든 에이전트의 구성을 점검하고 실제 실행 단계로 이동합니다. 에이전트 정의를 저장하는 것과 실행 서비스를 배포하는 것은 서로 다른 작업입니다. 저장만 한 에이전트는 채팅할 수 없습니다.
배포 전 구성 점검하기
에이전트 빌더 실습을 열고 다음을 확인합니다.
- 시스템 지시문에 도구, 액터, 범위 확인 조건이 들어 있음
- 배포·채팅 경로를 진행한다면 모델에 같은 컬렉션의 등록된 LLM 모델이 선택됨
- 기능 구성에
텍스트 정리 도구와요청 범위 확인 도구가 선택됨 - 기능 구성에 확인 정책이 적용된
승인 후 실행 액터가 선택됨 - 레슨 4의 RAG 단계를 완료했다면
응답 정책 검색 도구도 선택됨
RAG 도구는 모델과 지식 검색 환경이 준비된 경우에만 포함합니다. 기본 실습의 예상 선택 수는 도구 2개와 액터 1개입니다.
상단의 저장을 선택합니다. 저장은 현재 편집 내용을 에이전트 정의에 반영하지만 실행 중인 배포를 자동으로 교체하지 않습니다.
모델 준비 상태에 따라 실습 경로 선택하기
모델 영역에 다음 안내가 표시될 수 있습니다.
이 컬렉션에 등록된 LLM 모델이 없습니다. 이 에이전트를 실행하려면 해당 컬렉션에 모델을 먼저 등록해야 합니다.
이 상태에서는 배포 버튼이 비활성화되고 버튼 설명에 "배포하기 전에 제공자와 모델을 선택하세요."가 표시됩니다. 다음 두 경로 중 현재 환경에 맞는 하나를 선택합니다.
| 현재 상태 | 진행할 경로 | 완료 기준 |
|---|---|---|
| 같은 컬렉션에 사용할 수 있는 LLM 모델이 있음 | 배포·채팅 경로 | 모델 선택, 저장, 배포 후 채팅과 실행 기록 확인 |
| 등록할 LLM 엔드포인트나 자격증명이 없음 | 구성 점검 경로 | 도구·액터 개별 테스트, 에이전트 연결 수, 액터 확인 정책 확인 |
모델이 있는 경우
- 모델 영역의 이 컬렉션에 모델 등록하기를 선택하거나 AI → LLM 모델 → 등록으로 이동합니다.
- 조직의 모델 관리자에게 받은 제공자, 모델 id, 엔드포인트, API 키를 사용해 같은 컬렉션에 모델을 등록합니다.
- 가능하면 등록 화면의 연결 확인으로 엔드포인트를 먼저 검사합니다.
- 에이전트 빌더로 돌아와 등록한 모델을 선택하고 저장합니다.
모델이 없는 경우
모델 엔드포인트와 자격증명이 없다면 임의의 값을 사용하지 않습니다. 다음 항목을 확인하면 구성 점검 경로를 완료한 것입니다.
course_normalize_text와course_check_scope의 테스트 실행이 성공합니다.course_confirm_action의 테스트 실행이 성공하고 확인 정책이 확인입니다.- 에이전트의 기능 구성에 도구 2개와 액터 1개가 연결돼 있습니다. RAG 도구도 만들었다면 도구는 3개입니다.
- 레슨 4에서 만든 지식에
response_policy문서와 청크 1개가 보입니다.
모델이 없는 환경에서는 이후 에이전트 배포하기부터 실행 기록에서 실패 단계 찾기까지 건너뜁니다. 이는 실습 실패가 아니라 모델이 필요한 실행 단계만 제외한 정상 완료 경로입니다.
에이전트 배포하기
이 절부터 실행 기록 확인까지는 배포·채팅 경로입니다. 모델을 선택하고 저장하면 배포 버튼을 사용할 수 있습니다.
- 상단의 배포를 선택합니다.
- 배포가 진행되는 동안 기다립니다.
- 에이전트가 실행 중이라는 상태를 확인합니다.
배포는 저장된 정의를 기준으로 런타임 서비스를 준비합니다. 저장하지 않은 편집 내용은 배포에 포함되지 않으므로 항상 저장 → 배포 순서를 지키세요.
미리보기와 채팅의 차이
상단의 미리보기를 선택하면 빌더 안에서 현재 에이전트를 간단히 테스트할 수 있습니다.
- 미배포 상태에서는 배포 후 테스트와 에이전트를 배포하면 여기서 테스트할 수 있습니다가 표시됩니다.
- 배포 후 미리보기는 빠른 확인용이며 대화 기록을 영구 세션으로 남기지 않습니다.
- 대화와 단계별 실행 기록을 계속 확인하려면 에이전트 목록에서 채팅을 열거나 전체 채팅 화면으로 이동합니다.
채팅 화면에 직접 들어갔을 때 에이전트 미배포와 "에이전트가 배포되지 않았습니다. 먼저 배포하세요."가 표시되면 배포가 끝나지 않았거나 중지된 상태입니다. 에이전트 빌더로 돌아가 배포 상태를 확인합니다.
세 가지 대화로 실행 확인하기
전체 채팅 화면에서 다음 요청을 각각 새 대화로 확인합니다. AI 에이전트 모드에서는 LLM이 연결된 리소스를 선택하므로, 아래 호출 순서는 기대 결과이지 강제된 실행 순서가 아닙니다.
1. 도구만 호출하는 요청
" Hello D.Hub "를 정리해 줘. 결과는 기록하지 마.
확인할 내용:
course_check_scope를 호출했다면normalize_text를 허용하는가course_normalize_text가 호출되는가- 최종 답변에
hello d.hub와 길이 11이 표시되는가 course_confirm_action은 호출되지 않는가
2. 허용 목록에 없는 요청
delete_data 작업을 실행해 줘.
확인할 내용:
course_check_scope를 호출했다면 결과가allowed: false인가- 다른 도구나 액터를 호출하지 않는가
- 에이전트가 지원하는
normalize_text,record_result작업을 안내하는가
AI 에이전트가 범위 확인 도구를 건너뛴다면 레슨 5에서 설명한 것처럼 지시문만으로 실행 순서를 강제할 수 없다는 증거입니다. 고정 순서가 필요하면 워크플로우 모드로 다시 구성합니다.
3. 액터 승인이 필요한 요청
" Hello D.Hub "를 정리한 뒤 그 결과를 기록해 줘.
먼저 범위 확인과 문자열 정리 도구의 호출 여부를 확인합니다. 그다음 결과에 따라 진행합니다.
- 승인 카드가 표시됨 — 카드에
course_confirm_action과message인자가 보이는지 확인합니다. 거부를 선택하면 액터가 실행되지 않고 상태가 거부됨으로 바뀌어야 합니다. 새 대화에서 같은 요청을 다시 보내 승인을 선택하면 상태가 승인됨으로 바뀌고 액터 결과가 표시돼야 합니다. - 승인 카드가 표시되지 않음 — 실행 기록에서
course_confirm_action호출이 있는지 확인합니다. 호출이 없다면 LLM이 액터를 선택하지 않은 것이며, 일반 문장으로 기록했다고 답해도 액터가 실행된 것은 아닙니다. 도구·액터 설명과 시스템 지시문을 더 구체화한 뒤 저장·재배포해 다시 확인합니다.
승인 카드가 보이는 동안에는 먼저 승인이나 거부로 응답해야 새 메시지를 보낼 수 있습니다. 지시문을 보완해도 반드시 같은 순서를 보장해야 한다면 AI 에이전트 모드가 아니라 워크플로우 모드로 구성합니다.
실행 기록에서 실패 단계 찾기
배포된 에이전트의 전체 채팅 화면 상단에는 채팅과 실행 기록 전환이 표시됩니다. 대화를 실행한 뒤 실행 기록을 선택합니다.
- 확인할 턴을 선택합니다.
- 단계 목록에서
llm,tool,actor,approval종류를 순서대로 확인합니다. - 각 단계의 상태, 지연 시간, 입력 또는 인자, 출력 또는 결과, 오류를 확인합니다.
- 모델 단계에서는 실제 프롬프트와 출력, 모델 이름, 토큰 정보를 확인합니다.
- 도구·액터 단계에서는 호출 인자와 반환값이 문서의 예상값과 같은지 비교합니다.
실행 기록이 비어 있다면 먼저 채팅에서 응답이 끝날 때까지 기다립니다. 아직 대화를 선택하지 않았다면 대화를 시작하거나 선택하면 실행 기록을 볼 수 있습니다. 문구가 표시됩니다.
문제를 찾을 때는 다음 순서로 진행하는 것이 효율적입니다.
| 증상 | 먼저 확인할 곳 | 해결 방향 |
|---|---|---|
| 배포 버튼 비활성화 | 모델 선택 | 같은 컬렉션에 LLM 모델 등록 후 선택 |
| 채팅에 에이전트 미배포 표시 | 배포 상태 | 빌더에서 저장 후 배포 |
| 도구가 호출되지 않음 | LLM 단계와 시스템 지시문 | 도구 설명과 호출 조건을 구체화 후 재배포 |
| 도구 실행 오류 | 도구 단계의 인자·오류 | 도구의 테스트 실행으로 같은 입력 재현 |
| 승인 카드가 표시되지 않음 | 실행 기록의 액터 호출 | 호출이 없으면 액터 설명·지시문 보완, 고정 순서는 워크플로우 사용 |
| 액터가 바로 실행됨 | 액터의 확인 정책 | 확인 정책을 확인으로 저장 후 재배포 |
| 수정 내용이 반영되지 않음 | 재배포 필요 표시 | 저장 후 재배포 |
필요하면 내보내기에서 대화의 전체 실행 기록을 Markdown 또는 JSON으로 저장해 함께 검토할 수 있습니다. 민감한 입력, 모델 프롬프트, 도구 결과가 포함될 수 있으므로 외부 공유 전 내용을 확인하세요.
최종 자가 점검
- 저장과 배포가 서로 다른 작업임을 이해했는가
- 모델 미등록과 에이전트 미배포 상태의 메시지를 구분할 수 있는가
- 모델이 있다면 도구 호출과 범위 거부를 확인하고, 액터 호출이 생성된 경우 승인·거부를 확인했는가
- 모델이 없다면 도구·액터 개별 테스트와 에이전트 연결 상태로 구성 점검 경로를 완료했는가
- 수정 후 재배포가 필요한 이유를 이해했는가
- 실행 기록에서 실패한 단계의 입력, 출력, 지연 시간, 오류를 찾을 수 있는가
- 미리보기와 전체 채팅의 기록 보존 차이를 이해했는가
에이전트 빌더 코스를 마쳤습니다
이 코스에서는 에이전트 생성부터 Python 도구 테스트, 액터 확인 정책, 지식 문서와 RAG 준비, 허용 목록, 배포 및 실행 기록까지 실습했습니다. 운영 환경에서는 실제 업무에 맞춰 워크플로우 순서, 서버 권한, 비밀정보 관리와 모니터링 정책을 추가하세요.
다음 학습은 목적에 따라 선택할 수 있습니다.
- 관리자 코스 — 사용자, 역할, 세분화된 접근 제어 구성
- 데이터 엔지니어 코스 — 데이터 적재와 실행 파이프라인 구성
- 온톨로지 모델러 코스 — 엔티티와 관계를 모델링해 에이전트가 사용할 데이터 의미 확장