8.1. 연동 서비스 구성
개요
AAS 는 혼자 동작하지 않고 여러 서비스와 연결해 동작합니다. 이 장은 어느 연동이 끊기면 사용자가 무엇을 겪는지, 관리자가 화면에서 무엇을 확인할 수 있는지, 무엇을 운영자에게 알려야 하는지를 정리합니다.
권한: 일반 사용자와 관리자가 화면에서 볼 수 있는 내용입니다. 연동을 설치하고 고치는 일은 운영자가 합니다.
운영자는 AAS 를 설치하고 서버를 관리하는 사람입니다(용어 사전). 서버 설치와 설정은 이 매뉴얼의 범위가 아닙니다. 설치와 변경은 운영자에게 문의하거나, COP(OPENMARU Container Orchestration Platform) 설치 가이드의 AAS 설치 장을 봅니다.
연동 서비스 한눈 에 보기
| 서비스 | 끊기면 사용자가 겪는 일 | 관리자가 확인할 곳 |
|---|---|---|
| SSO(Single Sign-On, 로그인 서버) | 로그인하지 못합니다. | 로그인 화면의 안내 문구, 「사용자·권한」 화면 위의 안내 |
| 모델 서버(LiteLLM) | AI 에이전트가 답하지 않습니다. | 대시보드 「운영 정보」, 「내 AI 에이전트 › 모델」 |
| 스킬 허브(SkillHub) | 스킬을 설치하지 못하고 설치 요청이 대기합니다. | 대시보드 「운영 정보」, 「스킬 허브」 화면 |
| 받아쓰기·읽어 주기 서버 | 「말로 입력」이 막히거나 읽어 주기가 안 됩니다. | 채팅 입력칸의 버튼 |
| 사내 위키 연결 | AI 에이전트가 위키 글을 읽거나 쓰지 못합니다. | 프로파일의 MCP 서버 목록 |
SSO (Single Sign-On)
SSO 는 한 번 로그인해 여러 서비스를 쓰는 방식입니다. AAS 는 별도의 로그인 서버로 사용자를 확인합니다. 사용자가 AAS 주소로 들어가면 로그인 화면으로 이동합니다. 로그인이 안 되는 증상은 2.5. 로그인과 세션과 A.2. 문제 해결에 있습니다.
| 항목 | 설명 |
|---|---|
| 관 리자 | 세 가지 중 하나에 해당하는 사람이 관리자입니다. 로그인 서버에서 관리자 역할을 받은 사람, 「사용자·권한」 화면에서 관리자로 지정한 사람, 설치할 때 운영자가 관리자로 지정한 사람입니다. |
| 설치 때 지정된 관리자 | 「사용자·권한」 화면에서 권한을 바꾸거나 사용 중지·삭제할 수 없습니다. 바꾸려면 운영자에게 요청합니다. |
| 로그인을 끈 설치 | 모든 사람이 관리자로 취급됩니다. 로컬 시험용이며 이 컴퓨터에서만 접속할 수 있습니다. 「사용자·권한」 화면 제목 아래에 「로그인이 꺼져 있습니다」가 나옵니다. |
로그인 서버의 역할과 그룹 설정은 운영자가 합니다. 관리자를 늘리는 화면 절차는 2.3. 관리자와 팀 관리자 지정을 봅니다.
SSO 와 관련된 화면 영향은 다음과 같습니다.
- 로그인을 켠 설치에서만 「사용자·권한」 화면에 「Claude Code 연결」 탭이 나옵니다.
- 부서는 「사용자·권한」 화면의 「부서」 탭에서 관리합니다.
- 설치할 때 만든 기본 계정(이름은 보통
aas-admin)의 비밀번호는 공개된 값일 수 있습니다. 「사용자·권한」 화면에 이 계정이 있으면 운영자에게 비밀번호를 바꿨는지 묻습니다. 비밀번호는 운영자가 로그인 서버에서 바꿉니다.
모델 서버(LiteLLM)
LiteLLM 은 여러 AI 모델을 한 주소로 쓰게 해 주는 중계 서버입니다. AI 에 이전트의 대화, 보조 작업, 질문 검사(가드레일)가 모두 이 서버를 거칩니다.
| 확인 위치 | 보이는 것 |
|---|---|
| 대시보드의 「운영 정보」 | 「LiteLLM 정상」「LiteLLM 연결 안 됨」「LiteLLM 확인 전」 중 하나 |
| 「내 AI 에이전트 › 모델」 | 모델 목록. 연결을 확인할 수 없으면 「LiteLLM 확인 불가」가 나옵니다. 「점검」으로 모델에 1토큰짜리 호출을 한 번 보내 볼 수 있습니다(관리자만). |
| 채팅 | 모델 서버가 응답하지 않으면 답이 나오지 않습니다. 가드레일이 막은 질문은 거절됩니다. |
「LiteLLM 연결 안 됨」이 나오면 운영자에게 알립니다. 알릴 때는 대시보드 「운영 정보」 문구와 사용자가 겪은 증상을 함께 전합니다. 모델 목록과 연결 확인은 4.1. 모델, 막힌 요청 확인은 4.2. 안전장치를 봅니다.
스킬 허브(SkillHub)
AAS 는 스킬 패키지를 스킬 허브에 보관합니다. 허브는 AAS 화면에서만 씁니다.
- 허브에는 별도 접속 주소(웹 화면)가 없습니다. 목록 보기, 설치, 게시는 모두 AAS 의 「스킬 허브」 화면에서 합니다.
- 스킬 설치 요청은 AAS 서버의 설치 도우미가 순서대로 처리합니다. 도우미가 멈추면 대시보드의 「운영 정보」에 「스킬 허브 배달기 멈춤」이 나옵니다. 이때 운영자에게 알립니다.
- 허브 연결이 설정되지 않은 설치에서는 「스킬 허브」 화면에 「스킬 허브 주소가 설정돼 있지 않습니다」가 나옵니다. 운영자에게 알립니다.
- AAS 기본 스킬은 AAS 서버가 허브에 게시합니다. 6.3. 기본 스킬과 새 버전 알림을 봅니다.
- 공용·제한 같은 구분은 6.1. 스킬 허브와 네임스페이스를 봅니다.
참고: COP 설치 가이드는 같은 구성 요소를 「스킬 마켓(SkillHub)」으로 부릅니다. AAS 화면의 「스킬 허브」와 같은 것입니다.
받아쓰기·읽어 주기 서버
받아쓰기와 읽어 주기는 선택 기능입니다. 설치할 때 켠 경우에만 화면에 나옵니다. 켜기와 끄기는 운영자가 합니다.
| 기능 | 화면 | 켜지 않았거나 끊겼을 때 |
|---|---|---|
| 받아쓰기 | 채팅 입력칸의 「말로 입력」 버튼. 최대 1분 녹음하고 녹음은 저장하지 않습니다. | 버튼이 보이지 않습니다. 「지금 받아쓰기가 많습니다. 다시 시도를 눌러 주세요」가 나오면 잠시 뒤 다시 시도하게 합니다. |
| 읽어 주기 | AI 답 아래의 읽어 주기와 「설정 › 내 화면」의 목소리 고르기 | 읽어 주기를 쓸 수 없습니다. |
받아쓰기는 사용자의 AI 에이전트 작업공간이 연결돼 있어야 합니다. 작업공간이 멈춰 있으면 「AI 에이전트 작업 공간이 연결되지 않아 말로 입력을 쓸 수 없습니다」가 나옵니다. 이 경우 3.2. 작업공간 상태와 다시 시작을 봅니다. 버튼이 없다고 문의가 오면 운영자에게 받아쓰기를 켠 설치인지 묻습니다.
사내 위키 연결
사용자의 AI 에이전트가 사내 위키(Docmost, Outline)의 글을 읽고 쓰게 할 수 있습니다. 사용자가 프로파일에서 위키의 MCP(Model Context Protocol) 서버를 추가해 연결합니다. 화면 절차는 사용자 매뉴얼의 5.7. 사내 위키 연결 스킬을 봅니다. 관리자가 알아 둘 점은 세 가지입니다.
| 항목 | 설명 |
|---|---|
| 키 | 사용자마다 자기 키를 넣습니다. 공용 서비스 계정 키는 쓰지 않습니다. |
| 권한 | 위키가 판단합니다. AI 에이전트는 키를 넣은 사용자가 위키에서 할 수 있는 일만 합니다. |
| 쓰기 | 처음에는 읽기만 켜져 있습니다. 쓰기는 사용자가 따로 켭니다. |
주의: 오피스나 회의실에서 다른 사람이 이 AI 에이전트에게 일을 시켜도 키를 넣은 사용자의 권한으로 위키에 씁니다. 쓰기를 켜는 사용자에게 이 점을 안내합니다.