본문으로 건너뛰기
Ankole

빠른 시작

AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/quickstart/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

Ankole 배포 방식

프라이빗 Ankole 배포 인스턴스는 하나의 컨트롤 플레인과, Agent마다 하나씩 할당되는 Agent Computer Worker로 구성됩니다. 컨트롤 플레인은 영속적인 도메인 상태와 감독을 총괄하는 관리 플랫폼이고, Worker는 각 Agent의 전용 작업 컴퓨터 역할을 하는 실행 환경입니다.

동료마다 각자의 업무용 컴퓨터를 쓰듯 Agent끼리도 Worker를 공유하지 않습니다. Agent가 생성되면 컨트롤 플레인이 지정된 WorkerProvider를 통해 전용 Worker를 자동으로 프로비저닝하며, 중지·교체·삭제까지 전 생애주기를 관리합니다.

모든 배포 환경에는 PostgreSQL, 드라이브 파일 스토리지, Agent별 영구 Home 볼륨이 필요합니다. 기본 Kubernetes 차트는 공유 ReadWriteMany Home PVC와 별도의 ReadWriteOnce 캐시 PVC를 사용합니다. Home 볼륨은 반드시 백업해야 하지만 캐시 볼륨은 백업하지 않아도 됩니다.

하나의 사이트 안에 여러 테넌트를 둘 수 있습니다. 사이트 관리자는 공유 인프라를 운영하고, 각 테넌트는 소속 사용자·Agent·Brain·외부 연동을 독립적으로 소유합니다. 사이트 관리 콘솔의 기본 경로는 /site-admin-console이며, 최초 기동 전에 ANKOLE_SITE_ADMIN_CONSOLE_PATH(Helm: controlPlane.siteAdminConsolePath)로 변경할 수 있습니다.

이 가이드에서 사용하는 용어

다음 표는 Ankole 문서와 화면 전반에서 사용하는 핵심 용어를 정리한 것입니다. 괄호 안의 표기는 외부 플랫폼이나 설정 필드, API 명칭에 대응하며, 이후 본문에서는 짧은 형식을 주로 사용합니다.

정식 용어 의미 짧은 형식
Site 공유 인프라와 사이트 관리자를 갖춘 하나의 전체 Ankole 배포 단위 Site
Tenant 사이트 내 개별 조직의 사용자, Agent, Brain, 외부 연결 및 작업 공간 Tenant
Principal Ankole 안에서 신원과 권한을 부여받는 주체(사람, Agent, 시스템 서비스) Principal
Identity Provider (IdP) Console SSO 로그인을 제공하고 구성원·연락처·조직도를 동기화하는 외부 신원 소스 IdP
Chat platform Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp, 이메일 메일함 등 외부 대화 플랫폼 Platform
Channel Provider 메시지를 수신하고 Agent 답변을 발송하는 개별 채팅 앱 또는 봇 설정 Channel Provider
Conversation 사람과 Agent가 함께 참여하는 대화 공간. 네이티브 메시지는 Ankole을, 외부 메시지는 해당 플랫폼을 정본으로 삼습니다 Conversation
Message 대화 참여자에게 표시되는 확정된 메시지 기록 Message
Signal 메시지 도착, 예약 시각 도래, 외부 이벤트, 작업 완료 등으로 발생하는 영속적 트리거 Signal
Session 자체 시그널 큐와 복구 가능한 진행 상태를 지닌 실행 컨텍스트. 대화, 정기 작업, 백그라운드 작업 또는 워크플로 태스크에서 사용 Session
Delivery 외부 대화 채널로 내보내는 메시지의 영속적인 전송 의도, 시도 이력 및 최종 결과 Delivery
Signal Routing Rule (Signal Binding) 시그널 소스의 메시지나 이벤트를 대상 Agent로 연결하는 라우팅 규칙 Routing rule
LLM Provider 모델 서비스 엔드포인트, 자격 증명, 사용 가능 모델 목록을 담는 설정 LLM Provider
Model Profile Site -> Pod -> Agent/System 계층으로 상속되는 능력 슬롯(primary, light, heavy 및 멀티모달·검색 슬롯) Model Profile

Agent가 setup을 완료하게 하기

Codex, Claude Code 등 터미널을 제어할 수 있는 코딩 Agent에 아래 프롬프트를 전달해 초기 설치를 맡길 수 있습니다:

https://ankole.agentbull.com/ko-KR/docs/quickstart/index.md 문서를 참고해 프라이빗 Ankole 배포 인스턴스를 설치하고 구성하는 과정을 도와주세요. 먼저 현재 환경을 점검한 뒤 Docker Compose, Kubernetes, 또는 소스 설치 중 가장 적합한 방식을 추천해 주세요. 이어서 이메일 인증(Email OTP) 또는 엔터프라이즈 SSO Identity Provider(IdP) 로그인 설정과 LLM Provider, Agent, Channel Provider, Signal Routing Rule(Signal Binding) 설정을 안내해 주세요. 제가 로그인 방식과 메신저 플랫폼을 미리 지정하지 않았다면 어떤 로그인 방식(SMTP 이메일 인증 또는 엔터프라이즈 IdP)과 채팅 플랫폼을 사용할지 먼저 물어봐 주세요. 임의로 대신 선택하지 마세요. 채팅이나 명령어 출력에 시크릿을 절대 노출하지 마세요. 제가 선택한 메신저에서 실제 Agent 응답을 수신했을 때만 작업을 완료로 처리하세요.

1. Ankole 배포

단일 호스트 환경에는 Docker Compose를, 엔터프라이즈 운영 환경에는 Kubernetes를 사용하세요. 로컬 개발이나 디버깅이 목적이라면 소스 코드에서 직접 실행합니다.

테넌트 페이지는 <tenant-slug>.<site-host>(예: team.ankole.example.com)를 사용합니다. 공개 배포에서는 각 테넌트 호스트의 DNS, HTTPS 인증서, 프록시 또는 Ingress 라우팅을 구성해 같은 컨트롤 플레인으로 연결하세요. 아래 Compose의 Caddy 설정과 Helm의 Ingress 예시는 사이트 호스트만 대상으로 합니다.

Worker 설치 이름(installation)은 1~20자의 영문 소문자, 숫자, 하이픈(-)만 사용할 수 있으며 첫 글자와 마지막 글자는 영문자 또는 숫자여야 합니다(예: e2e-1011b01). Docker Compose에서는 ANKOLE_WORKER_INSTALLATION(기본값 ankole), Helm에서는 worker.installation(비워 두면 릴리스 이름 사용)으로 지정합니다. Worker 리소스 이름과 영구 Home 저장소 경로에 이 값이 사용되므로 첫 기동 전에 결정하고 설치 후에는 변경하지 마세요.

단일 호스트에서 PostgreSQL 18, ankole-function-runtime, 컨트롤 플레인, Caddy를 함께 실행하며, 선택한 프로바이더가 Agent별 전용 Worker를 생성합니다.

시작하기 전에

  • Linux amd64 또는 arm64 컨테이너를 실행할 수 있는 Linux, macOS, Windows 호스트
  • Compose 플러그인이 포함된 Docker Engine 또는 Docker Desktop
  • 영속 디스크, 공개 DNS 이름, 그리고 인바운드 80·443 포트

기본 설정

Docker Compose로 설치하기

모델 프로바이더 API 키는 배포 설정 파일에 넣지 마세요. 로그인 후 Console에서 안전하게 등록합니다.

  1. 01

    배포 패키지 가져오기

    bash
    git clone https://github.com/AgentBull/ankole.git
    cd ankole/tools/deploy/docker-compose
    cp .env.example .env
    chmod 600 .env
  2. 02

    독립된 시크릿 네 개 생성하기

    아래 명령을 복사해 실행한 뒤 출력된 네 줄을 모두 .env 파일에 붙여 넣으세요.

    bash
    printf '%s\n' \
      '# PostgreSQL database password' \
      "POSTGRES_PASSWORD=$(openssl rand -hex 24)" \
      '' \
      '# ANKOLE master encryption key' \
      "ANKOLE_SECRET_BASE=$(openssl rand -hex 32)" \
      '' \
      '# Erlang distribution cookie of the control plane' \
      "RELEASE_COOKIE=$(openssl rand -hex 32)" \
      '' \
      '# Shared token between the control plane and ankole-function-runtime' \
      "ANKOLE_FUNCTION_RUNTIME_TOKEN=$(openssl rand -hex 32)"
  3. 03

    Docker 소켓 그룹 설정하기

    컨트롤 플레인은 Docker 소켓을 통해 Worker 컨테이너를 생성합니다. 컨트롤 플레인은 비특권 사용자로 실행되며, 컨테이너 내부에서 소켓을 소유한 그룹 권한을 통해 소켓에 접근합니다.

    Linux에서는 아래 명령이 출력하는 그룹 ID를 .env의 ANKOLE_DOCKER_GID에 입력하세요. macOS의 Docker Desktop에서는 호스트의 소켓 그룹과 무관하게 컨테이너 내부에 그룹 0 소켓이 마운트되므로 ANKOLE_DOCKER_GID=0으로 설정하세요. ANKOLE_DOCKER_SOCKET은 소켓 경로가 기본값(/var/run/docker.sock)이 아닐 때만 지정합니다.

    bash
    stat -c %g /var/run/docker.sock   # Linux

    Docker 소켓 접근 권한은 호스트의 root 권한과 맞먹습니다. 해당 호스트 전체를 신뢰할 수 있는 퍼스트파티 컴퓨팅 경계로 다루세요.

  4. 04

    공개 호스트 설정하기

    ANKOLE_HOST에는 이 서버를 가리키는 공개 DNS 이름을 설정하고, ACME_EMAIL에는 인증서 만료·갱신 안내를 받을 이메일 주소를 입력하세요.

    ANKOLE_HOST
    ankole.example.com
    사용자 접속과 외부 프로바이더 콜백에 사용할 공개 HTTPS 호스트입니다.
    ACME_EMAIL
    ops@example.com
    Caddy의 TLS 인증서 자동 발급·관리에 사용할 연락처 이메일입니다.
  5. 05

    스택 시작 및 확인하기

    Docker Compose가 PostgreSQL 18과 ankole-function-runtime을 먼저 띄우고 DB 마이그레이션을 마친 뒤 컨트롤 플레인과 Caddy를 시작합니다.

    bash
    docker compose pull
    docker compose up -d
    docker compose ps
  6. 06

    첫 설정 열기

    브라우저에서 https://<ANKOLE_HOST>/setup을 열고 로그에서 확인한 활성화 코드를 입력하세요.

    bash
    docker compose logs control-plane | grep "SETUP ACTIVATION CODE"

2. 로그인과 identity를 먼저 설정

Ankole은 조직 내부의 프라이빗 배포를 전제로 설계되었습니다. 한 사이트에 여러 테넌트를 둘 수 있으며, 각 테넌트의 구성원·Agent·시스템 서비스는 모두 Principal로 표현되고 권한은 AuthZ가 관리합니다. /setup을 완료하면 첫 관리자에게 사이트 관리 콘솔(/site-admin-console)용 siteadmin 권한과 기본 Pod의 pod_admin 권한이 함께 부여됩니다. 테넌트 단위 설정을 변경하기 전에는 Console에서 대상 테넌트가 선택되어 있는지 먼저 확인하세요.

/setup에서는 비밀번호 없이 6자리 인증 코드를 이메일로 받는 이메일 인증(Email OTP)(email_otp, SMTP 서버 사용)과, 직원·연락처·조직도까지 함께 동기화하는 엔터프라이즈 SSO Identity Provider(IdP) 가운데 하나를 선택합니다. 채팅 채널을 연결하기 전에 로그인 방식부터 먼저 설정하세요.

설정 항목 담당 역할 설정 위치
이메일 인증 (email_otp) 비밀번호 없는 6자리 이메일 인증 코드 로그인(authn.email.mail SMTP 발송 및 SiteCredential 바인딩)과 이메일 초대 /setup (이메일 인증), 또는 CLI mix ankole.authn.mail.put
Identity Provider (IdP) 엔터프라이즈 SSO 로그인 및 사내 디렉터리의 직원·연락처·조직도·권한 그룹 동기화 초기 /setup 완료 후 Console → Identity Providers
Channel Provider 사용자 메시지를 받고 Agent 답변을 보내는 메신저 앱 또는 봇 Console → Signal Routing

로그인 수단과 채팅 채널이 꼭 같은 플랫폼일 필요는 없습니다. 예를 들어 이메일 인증이나 Google Workspace로 로그인을 구성하고 Slack에서 Agent와 대화할 수 있으며, Entra ID로 신원 인증을 처리하면서 대화 채널로는 Lark, Slack, DingTalk, Teams, WeCom을 연결할 수도 있습니다.

선택한 로그인 방식 설정 완료

이메일 인증 또는 조직에서 사용 중인 엔터프라이즈 IdP 탭을 선택하세요. 각 엔터프라이즈 SSO 탭은 외부 플랫폼 콘솔 설정부터 첫 로그인 및 디렉터리 동기화 확인까지 순서대로 안내합니다.

엔터프라이즈 어댑터를 처음 활성화한 경우에는 첫 로그인을 마친 뒤 컨트롤 플레인을 한 번 재시작하세요. 컨트롤 플레인을 재시작하면 디렉터리 연결이나 Graph 구독 같은 플러그인 백그라운드 작업이 함께 시작됩니다.

하나의 Slack 앱으로 Console 로그인과 워크스페이스 구성원·사용자 그룹 동기화를 처리합니다. 기본 구성에는 OAuth 클라이언트 정보, Bot Token, App Token이 필요합니다.

시작하기 전에

  • Slack 앱을 생성하고 워크스페이스에 설치할 수 있는 관리자 권한
  • Ankole 인스턴스의 공개 HTTPS 주소
  • 최초 로그인에 사용할 워크스페이스 구성원 계정

기본 설정

Slack IdP 설정하기

  1. 01

    Ankole에서 callback URL 복사하기

    https://<ANKOLE_HOST>/setup을 열고 활성화 코드를 입력하세요. 플러그인 단계에서 Slack Adapter를 선택해 저장한 뒤 로그인 방식으로 Slack을 고릅니다.

    Configuration ID(Provider ID)는 slack-main으로 그대로 두고 Copy 버튼을 눌러 로그인 콜백 URL을 복사하세요(직접 타이핑하거나 수정하지 마세요).

  2. 02

    Slack 앱 만들기

    Slack API의 Your Apps 페이지를 열고 Create New App → From scratch를 선택하세요. 앱 이름을 입력하고 구성원들이 속한 대상 워크스페이스를 고릅니다.

    Basic Information → App Credentials 섹션에서 Client ID와 Client Secret을 복사하세요.

  3. 03

    로그인 callback 등록하기

    OAuth & Permissions → Redirect URLs로 이동해 Add New Redirect URL을 누르고 Ankole에서 복사한 전체 URL을 붙여 넣은 뒤 저장하세요.

    Ankole은 로그인 시 표준 openid, profile, email 스코프를 요청하므로 이를 챗봇용 스코프로 대체하지 마세요.

  4. 04

    디렉터리 액세스를 부여하고 Bot Token 받기

    OAuth & Permissions의 Bot Token Scopes 아래에 다음 세 가지 스코프를 추가한 뒤 Install to Workspace를 눌러 워크스페이스 설치를 승인하세요.

    • users:read

      구성원 프로필 읽기

    • users:read.email

      구성원 이메일 주소 읽기

    • usergroups:read

      사용자 그룹과 소속 구성원 읽기

    설치 후 발급된 Bot User OAuth Token(반드시 xoxb-로 시작)을 복사하세요. 추후 스코프를 변경할 때마다 앱을 다시 설치해야 새 권한이 반영됩니다.

  5. 05

    App Token 발급 및 Socket Mode 켜기

    Basic Information → App-Level Tokens에서 Generate Token and Scopes를 눌러 아래 스코프를 추가하고 생성된 xapp- 토큰을 복사하세요. 이어서 좌측 Socket Mode 메뉴를 열고 Enable Socket Mode를 켭니다.

    • connections:write

      App Token으로 Socket Mode 연결 열기

  6. 06

    디렉터리 이벤트 구독하기

    Event Subscriptions 메뉴에서 이벤트 수신을 켠 뒤 Subscribe to bot events 아래에 다음 다섯 가지 이벤트를 추가하세요.

    • team_join

      신규 구성원 워크스페이스 합류

    • user_change

      구성원 프로필 변경

    • subteam_created

      사용자 그룹 생성

    • subteam_updated

      사용자 그룹 정보 변경

    • subteam_members_changed

      사용자 그룹 구성원 변경

  7. 07

    Ankole에 Slack 설정값 입력하기

    Sync directory와 Sync directory changes를 모두 켠 채로 Validate configuration을 눌러 로그인을 시작하고 Slack 인증을 완료하세요.

    • Client ID: Basic Information에서 복사한 Client ID
    • Client Secret: 같은 페이지의 Client Secret
    • Workspace ID: 선택 사항. Slack 웹 URL의 /client/ 뒤에 나오는 T… 식별자를 넣으면 로그인 시 해당 워크스페이스를 기본 선택합니다(디렉터리 동기화 범위를 제한하지는 않음)
    • Bot User OAuth Token: xoxb- 토큰
    • App-Level Token: xapp- 토큰
  8. 08

    로그인과 최초 동기화 확인하기

    Slack 인증 후 Ankole로 돌아오면 첫 사용자에게 siteadmin(/site-admin-console의 Site Admin Console용)과 기본 Pod pod_admin 권한이 부여됩니다. Console → Identity Providers에서 slack-main을 열고 Run full sync를 실행하세요.

    동기화가 완료되면 Console → Principals 및 Principal groups에서 워크스페이스 구성원과 사용자 그룹이 정상 반영되었는지 확인합니다.

3. LLM Provider 추가 및 Agent 생성

먼저 LLM Provider를 등록하세요. Console에 로그인한 뒤 Providers → New provider를 열고 Provider 유형을 선택하고 API 키를 붙여 넣은 뒤 저장합니다. Provider ID는 Console이 제안하고 엔드포인트는 Provider의 기본값을 쓰므로, 주소는 Azure OpenAI처럼 리소스마다 주소가 정해지는 서비스나 자체 호스팅·호환 엔드포인트일 때만 입력하면 됩니다. Ankole은 Provider 자격 증명을 컨트롤 플레인 내부에 암호화해 저장하므로 배포 .env 파일이나 Agent 작업 공간 파일에는 절대 기록하지 마세요.

다음으로 Console → Model Profiles를 열어 핵심 언어 모델 슬롯(Site -> Pod -> Agent/System 상속 및 heavy -> primary, light -> primary 슬롯 간 폴백)의 Site 기본값을 설정합니다. 모든 Pod와 Agent가 이 값을 상속합니다:

프로필 첫 실행 용도
primary 주 추론 및 대화 모델(필수; light와 heavy가 비어 있을 때 이곳으로 폴백)
light 빈번한 경량 턴 및 ankole_brain 지식 추출
heavy 심층 종합 추론, Background Agent Jobs, Dreaming, Skill 교훈 검토

Site 기본값에서 검증된 Provider·모델을 primary에 바인딩해 두면 모든 Agent와 ankole_brain을 곧바로 실행할 수 있습니다. 전체 대화 경로가 정상 동작하는 것을 확인한 뒤에 light와 heavy를 역할별 전용 모델로 분리하세요.

Pod 안에서는 모든 내부 구성원에게 Pod Chat의 1:1 개인 어시스턴트가 자동으로 제공됩니다. Pod 대화방이나 외부 IM 라우팅에서 함께 일할 공유 전문 AI 동료를 만들려면 Agents → New Agent를 열고, 의미 있는 소문자 테넌트 범위 uid(예: research-analyst), 표시 이름, 역할, 소유자, WorkerProvider를 입력해 저장하세요. Agent는 개별 슬롯을 재정의하지 않는 한 Site 및 Pod 모델 프로필을 그대로 상속하며, 행동 계약과 시각 규칙은 Meta Ankole → Agents의 AGENTS.md 및 DESIGN.md에서 관리합니다.

4. 채팅 채널 연결 및 시그널 라우팅 규칙 생성

구성원은 별도의 라우팅 규칙 없이도 Pod Chat에서 즉시 개인 어시스턴트 및 AI 동료와 대화할 수 있습니다. 외부 메신저 플랫폼을 연결하려면 먼저 Console에서 해당 플랫폼의 Control Plane Plugin을 활성화하세요. Lark / Feishu처럼 Ankole.Connectors가 지원하는 플랫폼에서는 Pod → Connections(/connectors) 또는 Console에 공유 애플리케이션 연결(authConfigId)을 한 번 등록해 두면, 중복 앱을 만들거나 시크릿을 다시 입력하지 않고도 SSO, 디렉터리 동기화, IM Signal 라우팅, MCP 툴킷, 이벤트 트리거에서 동일한 앱 연결을 함께 재사용할 수 있습니다. 여러 AI 동료마다 서로 다른 봇 이름, 아바타, 권한 범위가 필요한 경우에는 Agent별로 전용 봇 연결을 등록하고 개별 라우팅 규칙으로 연결하세요.

발신자 계정을 연결하는 방식은 플랫폼 범주에 따라 다릅니다:

  • 엔터프라이즈 플랫폼(Slack, Teams, Lark/Feishu, DingTalk, WeCom): IdP에서 동기화한 디렉터리 Principal과 발신자가 곧바로 매칭됩니다.
  • 일반 소비자용 메신저(Telegram, Discord, LINE, WhatsApp): 사내 디렉터리 직원 레코드가 없으므로 관리자가 아이덴티티 → 대기 중인 매핑에서 새 발신자를 계정에 연결한 뒤부터 Agent가 응답합니다(단, WhatsApp에서 이미 인증된 전화번호가 등록된 계정과 일치하면 자동으로 매핑됩니다).
  • Email: 전용 메일함을 연결하며, 명시적인 Pod 이메일 신원 바인딩이 등록된 발신자만 허용합니다.

Slack은 Socket Mode를 사용합니다. Ankole이 아웃바운드 WebSocket 연결을 직접 열기 때문에 채팅 경로에 공개 Slack 웹훅이 필요하지 않습니다.

시작하기 전에

  • Slack 앱을 생성하고 설치할 수 있는 권한
  • 테스트용 채널 또는 다이렉트 메시지

기본 설정

Slack 앱 준비

  1. 01

    앱 생성 및 Socket Mode 활성화

    Slack 앱을 처음부터 새로 만듭니다. Basic Information에서 아래 scope를 포함한 App-Level Token을 발급한 뒤 Socket Mode를 활성화하세요.

    • connections:write

      App Token으로 Socket Mode 연결을 열 때 필요합니다

  2. 02

    채팅 및 채널 상태 이벤트 구독

    Event Subscriptions → Subscribe to bot events를 열고 아래 이벤트를 모두 추가하세요. Slack 어댑터가 처리하는 메시지, 리액션, 채널 상태 동기화에 꼭 필요한 이벤트 목록입니다.

    • app_mention

      채널 @멘션 수신

    • message.channels

      공개 채널 메시지 수신

    • message.groups

      비공개 채널 메시지 수신

    • message.im

      다이렉트 메시지 수신

    • message.mpim

      다자간 다이렉트 메시지 수신

    • reaction_added

      추가된 리액션 수신

    • reaction_removed

      제거된 리액션 수신

    • member_joined_channel

      채널에 참여한 구성원 동기화

    • member_left_channel

      채널에서 나간 구성원 동기화

    • channel_rename

      공개 채널 이름 변경 동기화

    • group_rename

      비공개 채널 이름 변경 동기화

    • channel_deleted

      채널 삭제 동기화

    • channel_archive

      채널 보관(아카이브) 동기화

  3. 03

    다이렉트 메시지 허용

    App Home → Show Tabs를 열고 Display Messages 탭을 켠 다음, Allow users to send Slash commands and messages from the messages tab을 선택하세요. Messages 탭 표시만 켜 두면 탭 화면만 보일 뿐 사용자가 Agent에게 다이렉트 메시지를 보낼 수 없습니다.

  4. 04

    인터랙티브 컴포넌트 활성화

    Interactivity & Shortcuts를 열고 Interactivity를 활성화하세요. Socket Mode가 기존 WebSocket 연결로 Block Kit 버튼 이벤트를 전달하므로 별도의 공개 Request URL은 입력하지 않아도 됩니다.

  5. 05

    채팅 Bot Token Scope 부여 및 앱 설치

    OAuth & Permissions → Bot Token Scopes에서 아래 scope를 모두 추가하세요. Ankole이 실제로 호출하는 Slack API만 추린 목록이므로 사용하지 않는 assistant, workflow, document, meeting 관련 scope는 부여하지 마세요.

    • app_mentions:read

      봇을 멘션한 메시지 읽기

    • channels:read

      공개 채널 및 구성원 동기화

    • channels:history

      공개 채널 메시지 읽기 및 답장 정합성 유지

    • groups:read

      비공개 채널 및 구성원 동기화

    • groups:history

      비공개 채널 메시지 읽기 및 답장 정합성 유지

    • im:read

      다이렉트 메시지 대화 동기화

    • im:history

      다이렉트 메시지 읽기 및 답장 정합성 유지

    • mpim:read

      다자간 다이렉트 메시지 및 구성원 동기화

    • mpim:history

      다자간 다이렉트 메시지 읽기 및 답장 정합성 유지

    • chat:write

      봇 메시지 전송, 수정, 삭제

    • reactions:read

      리액션 변경 수신

    • reactions:write

      리액션 추가 및 제거

    • files:read

      메시지 첨부 파일 읽기

    • files:write

      Agent가 보내는 파일 업로드

    • users:read

      채널 구성원 식별 및 봇 계정 제외

    scope를 변경한 뒤에는 워크스페이스에 앱을 다시 설치하고 새로 발급된 Bot Token을 Ankole에 반영하세요.

  6. 06

    Console 입력 필드 확인

    botToken
    xoxb-…
    Bot User OAuth Token입니다. xoxb- 접두사로 시작해야 합니다.
    appToken
    xapp-…
    Socket Mode용 App-Level Token입니다. xapp- 접두사로 시작해야 합니다.

Console에서 연결 완료

라우팅 규칙 하나는 단일 Channel Provider를 단일 Agent에 연결하며 어댑터 종류, 앱 자격 증명, 대상 Agent, 그룹 메시지 동작 모드를 담습니다. 봇마다 별도의 라우팅 규칙을 만드세요.

Console에서 Signal Routing → New routing rule을 열고 아래 항목을 입력합니다:

필드 입력할 값
Target Agent 3단계에서 생성한 Agent
Adapter Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp 또는 Email
Rule name slack-main, lark-main처럼 식별하기 쉬운 고정 이름
Group message mode 처음에는 addressed_only로 시작
Channel settings 위 채널 탭에서 준비한 자격 증명 및 설정값 붙여 넣기

규칙을 저장하면 목록에 활성화(enabled) 상태로 표시되어야 합니다. 자격 증명 검증 오류가 표시되면 어댑터 연결이 아직 열리지 않은 상태이므로, 메신저에서 테스트하기 전에 오류부터 해결하세요.

5. IM에서 Agent와 대화

테스트용 대화방에 봇을 초대한 뒤 메시지를 보내 보세요. 그룹 채팅에서는 아래처럼 명시적인 @멘션으로 대화를 시작합니다:

@Ankole 어떤 일을 할 수 있고, 어느 팀을 지원하고 있나요?

실제 모델 응답이 돌아오는 것을 확인한 다음, Meta Ankole → Agents에서 Agent의 AGENTS.md 및 DESIGN.md 계약을 다듬고 모델 프로필 티어와 그룹 채팅 응답 정책을 운영 환경에 맞게 조정하세요.

Agent가 응답하지 않으면

경계를 하나씩 좁혀 가며 다음 순서대로 점검하세요:

  1. 외부 플랫폼에서 최신 앱 버전이 게시되었고 테스트 사용자가 가용 범위에 포함되어 있는지 확인합니다.
  2. 대상 채널, 팀 또는 대화방에 봇이 정상 설치·초대되었는지 확인합니다.
  3. 필수 메시지 이벤트 구독과 권한 scope가 모두 켜져 있는지 확인합니다.
  4. 라우팅 규칙이 활성 상태이며 의도한 대상 Agent를 가리키는지 확인합니다.
  5. 대상 Agent에 대해 유효한 primary 모델 프로필이 해석되는지 확인합니다(Console → Model Profiles의 Site/Pod 기본값 또는 Agent별 재정의).
  6. LLM Provider 자격 증명과 모델 식별자가 유효한지 확인합니다.
  7. 환경 도구나 Codex 작업이 필요한 턴이라면 Console → Workers에서 해당 Worker의 상태와 시작 오류를 확인하세요. Agent를 생성하면 Worker의 최초 시작을 요청합니다. 유휴 상태로 Worker가 해제된 뒤에도 일반 질의응답과 컨트롤 플레인 도구는 준비된 Worker 없이 실행할 수 있습니다.

Docker Compose 환경에서는 docker compose logs -f control-plane으로 컨트롤 플레인 로그를 확인하고, docker ps -a --filter label=ankole.installation=ankole로 Worker 컨테이너 목록을 조회한 뒤 docker logs CONTAINER_NAME으로 개별 컨테이너 로그를 살펴보세요. Kubernetes 환경에서는 컨트롤 플레인 Pod와 Worker Pod 로그를 확인합니다. 로그를 점검할 때는 오류 메시지만 확인하고 환경 변수나 시크릿 값은 외부에 출력하지 마세요.

첫 응답까지 확인했다면 이어서 Agents, Signal 라우팅 규칙, Background Agent Jobs 가이드를 살펴보세요.