이 가이드는 Discourse AI - AI 봇의 에이전트(Agent) 설정 및 관리 방법을 설명합니다.
필요한 사용자 권한: 관리자(Administrator)
Discourse AI 봇에는 에이전트를 관리하기 위한 유연한 시스템이 포함되어 있습니다. 이 가이드에서는 다음 내용을 다룹니다:
- AI 에이전트 상호작용 방법
- 설정 옵션
- 고급 설정
- 지원되는 도구(Tools)
- 사용자 정의 가능성
AI 봇에 대한 정보 및 활성화 방법은 이 가이드에서 확인하세요.
에이전트(Agent)란?
에이전트는 Discourse 포럼에서 AI 엔진의 동작을 사용자 정의할 수 있는 강력한 기능입니다. 이는 AI의 응답과 상호작용을 안내하는 ‘시스템 메시지(System message)’ 역할을 하여, 보다 개인화되고 몰입감 있는 사용자 경험을 만드는 데 도움을 줍니다.
왜 에이전트를 사용해야 하나요?
에이전트를 사용하면 포럼의 맥락과 톤에 맞게 AI의 동작을 조정할 수 있습니다. 전문적인 환경을 위해 더 격식 차린 AI를 원하든, 커뮤니티 포럼을 위해 더 캐주얼한 AI를 원하든, 또는 역할극 게임(RPG)을 위해 특정 캐릭터를 구현하든, 에이전트는 이를 위한 유연성을 제공합니다.
그룹별 에이전트 접근 권한
또한, 특정 사용자 그룹이 특정 에이전트에 접근할 수 있도록 설정할 수 있습니다. 이를 통해 포럼의 각 섹션마다 다른 AI 동작을 설정하여 커뮤니티 상호작용의 다양성과 풍부함을 한층 더 높일 수 있습니다.
에이전트와의 상호작용
에이전트는 다음과 같은 여러 방식으로 상호작용할 수 있습니다:
- 개인 메시지(PM)
- 채팅 다이렉트 메시지(DM)
- 채팅 채널 멘션
- 공개 주제(Topic)에서
@example_bot_username을 통한 멘션
관리자는 네 개의 개별 토글을 통해 각 에이전트에 허용되는 상호작용 방법을 제어할 수 있습니다:
- 개인 메시지 허용: 사용자가 이 에이전트와 PM을 시작할 수 있도록 허용 (기본값: 활성화)
- 주제 멘션 허용: 주제(Topic)에서의
@mention이 응답을 트리거하도록 허용 - 채팅 다이렉트 메시지 허용: 이 에이전트와 채팅 DM을 허용 (채팅 플러그인 필요)
- 채팅 채널 멘션 허용: 채팅 채널에서의
@mention을 허용 (채팅 플러그인 필요)
설정 (Configuration)
에이전트를 설정하려면 discourse.example.com/admin/plugins/discourse-ai/ai-agents로 이동하세요.
주요 설정 옵션은 다음과 같습니다:
- 시스템 프롬프트(System prompt): 대화의 방향을 설정합니다.
- 비전 지원(Vision support): 비전 기능을 지원하는 LLM(예: GPT-4 Turbo, Claude 3)의 경우 활성화합니다.
- 기본 모델(Default model): 멘션 가능한 에이전트 및 기본 LLM 강제 사용이 활성화된 에이전트의 경우 필수입니다.
- 허용된 그룹(Allowed groups): Discourse 그룹 보안 설정을 사용하여 권한을 정의합니다.
- 업로드(Uploads): 추가 지식(텍스트 파일)을 인덱싱합니다 (RAG - 검색 증강 생성 사용).
- 활성화된 도구(Enabled tools): 특정 도구에 대한 접근을 제어합니다.
- 실행 모드(Execution mode): “default” 모드와 “agentic” 모드 중 선택합니다 (agentic 모드는 설정 가능한 토큰 제한 및 압축을 가진 다중 턴 도구 사용을 활성화합니다).
다음은 완전한 AI 에이전트 설정 화면의 예시입니다:
고급 설정 옵션
에이전트 편집기에는 몇 가지 고급 옵션이 제공됩니다:
- Temperature 및 top_p (nucleus sampling): 창의성과 예측 가능성의 균형을 조절합니다.
- 최대 컨텍스트 게시물 수(Max context posts): LLM에 전달되는 히스토리용 게시물 수를 제한합니다 - 게시물 수가 적을수록 비용은 줄지만, AI가 오래된 내용을 “잊게” 됩니다 (agentic 모드에서 사용 불가).
- 실행 모드(Execution mode): "Default"는 단일 패스 응답을 위해, "Agentic"는 다음을 가진 다중 단계 도구 사용을 위해 사용됩니다:
- 최대 턴 토큰(Max turn tokens): agentic 실행을 위한 토큰 예산
- 압축 임계값(Compression threshold): 컨텍스트 압축을 위한 백분율 임계값 (20-99%)
- 생각 과정 표시(Show thinking): 사용자에게 AI의 추론 과정을 표시합니다 (기본값: 활성화)
- 승인 요구(Require approval): 특정 작업 실행 전에 인간 승인을 요구합니다.
- 기본 LLM 강제(Force default LLM): 사용자가 이 에이전트에서 LLM을 변경하는 것을 방지합니다.
- 응답 형식(Response format): 구조화된 출력 형식을 구성합니다.
- 예시(Examples): AI의 동작을 안내하기 위한 Few-shot 예시 (사용자/어시스턴트 메시지 쌍).
- 업로드 옵션(Upload options):
- 청크 토큰(Chunk tokens): 문서 분할을 제어합니다.
- 청크 오버랩 토큰(Chunk overlap tokens): 청크 간 오버랩을 설정합니다.
- 대화 청크 검색(Search conversation chunks): 사용자 쿼리에 추가되는 문서 조각의 수.
- 질문 통합 LLM(Question consolidator LLM): 사용자 질문을 결정하기 위한 LLM을 선택합니다.
- RAG LLM 모델: RAG 처리를 위한 특정 LLM을 선택합니다.
업로드 지원 사전 요구 사항
업로드 지원을 사용하려면:
ai_embeddings_enabled설정을 활성화하세요.ai_embeddings_selected_model을 통해 임베딩 모델을 구성하세요.
Discourse AI는 다양한 임베딩 모델을 지원합니다. 호스팅 고객은 bge-large-en 모델에 대한 무료 접근 권한을 얻습니다.
셀프 호스터나 더 많은 선택지를 원하는 사람은 임베딩 모델을 셀프 호스팅하거나 Open AI, Google (Gemini) 등의 모델을 사용할 수 있습니다.
Discourse AI의 텍스트 분할
Discourse는 텍스트를 분할할 때 단락, 줄, 단어를 유지하기 위해 Recursive Character Text Splitter를 사용합니다. [[metadata YOUR METADATA HERE]] 구분자를 사용하여 텍스트 분할을 제어할 수 있습니다:
[[metadata about cats]]
a long story about cats
[[metadata about dogs]]
a long story about dogs
이 방법은 각 청크에 관련 데이터만 포함되도록 하여 "청크 오염(chunk contamination)"을 방지합니다.
AI 에이전트 디버깅
에이전트를 디버깅하려면:
ai_bot_debugging_allowed_groups설정에 지정된 그룹에 사용자를 추가하세요.- 이 그룹의 사용자는 AI 게시물 하단에 AI 디버깅 버튼을 볼 수 있습니다.
- 버튼을 클릭하여 디버깅 UI 모달에 접근하세요.
기억하세요: LLM에 모호하거나 도움이 되지 않는 정보를 제공하면, 이를 유용한 정보로 변환하는 데 큰 어려움을 겪을 것입니다.
지원되는 도구 (Tools)
Discourse AI는 다음과 같은 다양한 도구를 지원합니다:
항상 사용 가능
- Categories (카테고리)
- Time (시간)
- Search (검색)
- Read (읽기)
- Database Schema (데이터베이스 스키마)
- Search Settings (검색 설정)
- Setting Context (컨텍스트 설정)
- Random Picker (무작위 선택기)
- Web Browser (웹 브라우저)
- Search Meta Discourse
- JavaScript Evaluator (JavaScript 평가기)
- Researcher (리서처)
- Flag Post (게시물 신고)
- Close Topic (주제 닫기)
- Unlist Topic (주제 목록에서 제거)
- Lock Post (게시물 잠금)
- Delete Topic (주제 삭제)
- Edit Post (게시물 편집)
- Edit Category (카테고리 편집)
- Set Topic Timer (주제 타이머 설정)
- Set Slow Mode (슬로우 모드 설정)
- Move Posts (게시물 이동)
- Grant Badge (배지 부여)
GitHub 연동
- GitHub File Content (GitHub 파일 내용)
- GitHub Pull Request Diff (GitHub Pull Request 차이)
- GitHub Search Files (GitHub 파일 검색)
이 세 가지 도구는 항상 사용 가능합니다. 추가로:
- GitHub Search Code는
ai_bot_github_access_token설정이 입력되어야 합니다.
조건부 도구
- Tags 및 Edit Tags: 사이트에 태그 기능이 활성화된 경우 사용 가능
- Image generation (Image, Create Image, Edit Image): 관리자 UI를 통해 사용자 정의 이미지 생성 도구가 구성되어야 합니다.
- Google search:
ai_google_custom_search_api_key및ai_google_custom_search_cx설정이 입력되어야 합니다. - Artifacts (Create Artifact, Update Artifact, Read Artifact):
ai_artifact_security가 lax, hybrid, strict 중 하나로 설정된 경우 사용 가능 - Assign: Assign 플러그인이 설치된 경우 사용 가능
- Mark as Solved: Solved 플러그인이 설치된 경우 사용 가능
일부 도구는 추가 구성이나 API 키가 필요합니다.
사용자 정의 도구 지원
사용자 정의 도구 지원을 사용하여 자신의 도구를 만들 수 있습니다.
시스템 에이전트 사용자 정의
- 새 에이전트를 생성합니다.
- 사용자 정의하려는 에이전트의 시스템 프롬프트를 복사하여 붙여넣습니다.
- 필요에 따라 수정합니다.
- 중복을 피하기 위해 원본 시스템 에이전트를 비활성화합니다 (선택 사항).
검색 사용자 정의
새 에이전트의 검색을 사용자 정의하려면:
- 새 에이전트를 생성합니다.
- “search” 도구를 추가합니다.
- 다음을 포함한 검색 옵션을 구성합니다:
- 기본 검색 쿼리
- 최대 검색 결과 수
- 비공개 주제 포함 옵션
이를 통해 검색 권한을 위임하거나, 결과 수를 증가시키거나, 검색을 사이트의 특정 섹션으로 제한할 수 있습니다.
