프로젝트 소개

본 프로젝트는 《AG-UI 그룹 채팅 확장 프로토콜 표준 v1.0》을 구현한 그룹 채팅 프로토콜 허브(Hub)로, C# / .NET 10의 ASP.NET Core Minimal API로 작성되었습니다. '그룹 채팅'을 제3자 애플리케이션이 접속 가능한 프로토콜 계층으로 구축하여, 그룹 및 멤버의 생명주기, 메시지 팬아웃, 구독 및 실시간 다운링크가 동일한 이벤트 및 에러 코드 규약을 따르며, AI 에이전트가 그룹 멤버로 참여하는 구조입니다. 프로토콜 기능 - 그룹 생명주기: 생성, 업데이트, 해체 (GROUP_CREATED / GROUP_UPDATED / GROUP_DISBANDED). - 멤버 관리: 가입, 제거, 자발적 퇴장, 역할 및 프로필 변경 (GROUP_MEMBER_*). - 메시지 팬아웃: 사용자 메시지를 TEXT_MESSAGE_START/CONTENT/END 삼원조로 브로드캐스트하며, all, mentioned, private 세 가지 가시 범위를 제공하고 메시지 회수, 읽음 확인, 입력 중 상태를 지원합니다. - 구독 메커니즘: GROUP_SUBSCRIBE / GROUP_UNSUBSCRIBE / GROUP_SUBSCRIBE_ACK / GROUP_STATE_SNAPSHOT. - 듀얼 전송: WebSocket 전이중( /ws) 및 SSE 단방향 다운링크( /sse)를 제공하며 하트비트 유지 기능을 포함합니다. SSE는 HTTP 인터페이스를 통해 동적으로 구독 및 해지가 가능합니다. - 에이전트 트리거 규칙 (프로토콜 §6): 멘션 트리거, 전체 리스닝, 키워드 트리거, 컨텍스트 트리거(모델이 문맥에 따라 발언 여부 결정). - HTTP 업링크 API: 그룹 생성, 고객센터 지식베이스 발견/진입, 그룹명 자동 생성, 멤버 증감, 메시지 전송, 첨부파일 업로드/다운로드, 회수, 읽음 확인, 인간-기계 상호작용 결정, 스냅샷 및 멤버 리스트 등을 커버합니다. 에러는 code + message로 통일하여 반환하며, 상태 코드는 403/404/409/400으로 매핑됩니다. 쓰기 인터페이스는 토큰 신분으로 요청 본문의 신분 필드를 덮어쓰며, 읽기 인터페이스는 호출자가 그룹 멤버인지 검증합니다. 에이전트 및 메모리 - AguiGroupChat.Agents: Microsoft Agent Framework를 기반으로 IAgentGateway를 구현했습니다. Mock 제공자를 통해 즉시 사용 가능하며, OpenAI 호환 엔드포인트(Ollama / vLLM / Azure OpenAI / DeepSeek) 설정이 가능합니다. 트리거 시 텍스트 이벤트를 스트리밍으로 환류하며, 함수 호출 시 TOOL_CALL_START를 팬아웃합니다. - 인간-기계 상호작용 (HITL): 도구에 ApprovalRequiredAIFunction를 표시하여 승인이 필요하도록 설정할 수 있습니다. 모델 호출 시 실행이 중단되고 AGENT_INTERACTION_REQUEST 상호작용 카드가 브로드캐스트되며, 트리거한 사용자만 승인 또는 거절할 수 있고 결정 후 동일 세션이 재개됩니다. - RAG 시맨틱 메모리: MemoryContextProvider가 검색 컨텍스트를 주입하며, 벡터는 pgvector에 저장됩니다. 임베딩은 HTTP 엔드포인트 또는 LLamaSharp 로컬 모델(예: bge-m3)을 사용합니다. 지식베이스는 문서 슬라이싱 및 검색을 지원하며 메모리 범위, TopK, 유사도 임계값 등을 조정할 수 있습니다. - 메모리 페르소나 타입: 각 디지털 직원별로 5단계 메모리 프리셋과 말투 모드를 설정할 수 있으며, 미설정 시 플랫폼 전역 설정을 따라 하위 호환성을 유지합니다. - 내장 도구 세트: 계산기, 단위 변환, 그룹 메모리 검색, 첨부파일 읽기 등이 포함되며, 인터넷 연결이 필요한 web_search / read_url은 기본적으로 비활성화되어 있습니다. - 이미지 이해: 이미지 첨부가 포함된 회신은 비전 모델로 라우팅되며, 이미지는 base64 멀티모달 콘텐츠로 전달됩니다. - 사고 모드 브릿지: 외부 서비스의 REASONING_MESSAGE_CONTENT는 독립 채널을 통해 전달되며, 프론트엔드에서 접이식 사고 과정 블록으로 렌더링됩니다. 애플리케이션 및 확장 기능 - 사용자 관리: 가입, 로그인, 로그아웃, 비밀번호 변경, 프로필 유지관리 기능을 제공합니다. PBKDF2 비밀번호 해시와 세션 토큰을 사용하며, WS/SSE는 토큰 인증을 지원합니다. 로그인 인터페이스에는 사용자 이름 열거 방지 및 실패 속도 제한 처리가 적용되었습니다. - 플랫폼급 RBAC: SuperAdmin / Admin / Operator / User 4단계 권한을 제공하며, 설정 리스트를 통한 부트스트래핑 또는 슈퍼 관리자의 온라인 부여가 가능합니다. 또한 사용자 그룹 및 그룹별 권한 부여를 통해 디지털 직원과 스킬의 가시성 화이트리스트를 관리합니다. - 스킬 라이브러리: prompt / shell / http / dotnet 네 가지 유형으로 구분되며, 실행 능력이 있는 스킬은 시스템 관리자만 수정할 수 있습니다. 자연어를 이용한 스킬 정의 생성 및 테스트 실행을 지원합니다. - 원클릭 조직 오케스트레이션: 한 문장의 요구사항 입력 시 SSE 스트리밍으로 직무 방안을 생성하며, 조직 구조, 스킬 및 배정 관계를 미리 본 후 일괄 저장하고 생성 시 그룹 채팅을 동시에 구축할 수 있습니다. - 1:1 채팅 및 고객센터 지식베이스: 디지털 직원과 멱등성 있는 프라이빗 1:1 채팅을 생성할 수 있습니다. 고객센터 지식베이스에서 일반 사용자는 참여자 신분으로 진입하며 세션은 서로 격리됩니다. - 글로벌 검색: 메시지, 시맨틱 메모리, 지식베이스를 교차 검색하며 가시성에 따라 결과를 필터링합니다. - 링크 프록시, 데이터 내보내기/가져오기, 런타임 모델 설정, 감사 로그 및 계정 탈퇴 등 기업 컴플라이언스 관련 기능을 제공합니다. 배포 및 프로젝트 형태 - Web 데모, 프로토콜 전용 Hub, Windows 데스크톱(WPF + WebView2), 크로스 플랫폼 데스크톱(Avalonia)의 네 가지 실행 방식을 제공합니다. 데스크톱 버전은 다중 인스턴스가 동일한 백엔드 프로세스를 공유할 수 있습니다. - 영속성 계층은 JSON 단일 파일 스냅샷 또는 postgres / mysql / sqlite 데이터베이스 중 선택 가능합니다. docker compose를 통해 postgres(pgvector) + 내장 Ollama + Web을 한 번에 실행할 수 있으며, 기본적으로 시맨틱 메모리가 활성화됩니다. - 제3자 접속 SDK(AguiClient + AguiRealtimeClient, net8.0/net10.0 지원), 예제 클라이언트, 유닛 및 E2E 테스트, Playwright 브라우저 자동화 스크립트가 포함되어 있습니다.