본문으로 건너뛰기
Ankole

Console API 참조

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

Console API는 다중 계정 브라우저 세션 인증을 사용합니다. 호출 시 Cookie 헤더로 암호화·봉인된 세션 쿠키를 전달하고 x-ankole-authentication 헤더로 활성 계정을 지정합니다. 서버에서는 RequireSiteAdminSession 플러그가 활성 관리자 세션과 사용자(Human) 접근 상태를 확인해 Ankole.AuthZ 액터(console_rest)를 바인딩하고, 이어서 Ankole.AuthZ.Authorizer가 각 Ash 액션에 대해 site_console:** 및 tenant_console:** 권한을 검증합니다. 인증에 실패하면 401이 반환됩니다. GET과 HEAD를 제외한 상태 변경 요청에는 브라우저 셸의 x-csrf-token 헤더가 필수이며, CSRF 토큰이 누락·만료되었거나 권한 인가가 거부되면 403이 반환됩니다.

모든 Console 구성 변경, 집계 조회, 감사 대상 시크릿 작업은 /api/v2 경로 아래에 열려 있습니다. 사이트 전체 관리 라우트는 /api/v2/site 하위 경로를 쓰고, 테넌트 범위 라우트는 현재 선택된 데이터 테넌트를 대상으로 동작합니다. 아래 표에는 각 라우트의 전체 경로를 기재했습니다.

v2 요청 본문과 응답은 JSON:API 미디어 타입인 application/vnd.api+json을 따르며 세부 페이로드 규격은 OpenAPI 스키마에 정의되어 있습니다. 일반 리소스의 생성과 수정은 data.type과 data.attributes 구조를 사용합니다. 반면 generic 액션은 액션 인자를 data 바로 아래에 배치하며 표준 JSON:API 리소스 문서 대신 타입이 지정된 결과 객체를 바로 반환할 수 있습니다(예: PUT /api/v2/worker-envs/EXAMPLE에 {"data":{"value":"example","secret":false}}를 보내면 worker_env 객체 반환). 스키마에 키셋(keyset) 페이지네이션이 선언된 목록 엔드포인트는 page[limit]와 page[after] 쿼리 파라미터를 지원합니다.

테넌트 범위 라우트를 호출할 때는 x-ankole-tenant: <테넌트 UUID> 헤더로 대상 데이터 테넌트를 지정하며, 헤더를 생략하면 호출자 본인이 속한 테넌트가 기본 선택됩니다. 존재하지 않거나 비활성 상태이거나 삭제가 진행 중인 테넌트를 지정하면 data_tenant_unavailable 오류와 함께 404가 반환됩니다. 이 헤더는 조회·조작할 대상 테넌트만 바꿀 뿐 호출자의 신원이나 사이트 관리자 권한을 변경하지 않으며, 사이트 범위 라우트(/api/v2/site/*)의 동작에도 영향을 주지 않습니다.

Console 및 사이트 관리 작업의 전체 명세는 /api/v2/openapi.json과 /api/v2/site/openapi.json에서 제공되며, 실제 API 라우트와 동일한 관리자 인증을 거쳐야 조회할 수 있습니다. 그 밖의 브라우저 JSON:API 영역도 각각 전용 OpenAPI 3.1 문서를 게시합니다. Pod 워크스페이스 및 pod_admin 전용 /api/v2/pod/admin/* 라우트는 /api/v2/pod/openapi.json에서, 브라우저 로그인 및 초기 설정 라우트는 /api/v2/browser/openapi.json에서 확인할 수 있습니다. 파일 업로드·다운로드는 아래에 설명된 /api/v2 네이티브 바이너리 라우트를 사용하며, 런타임 AI 호출이나 OIDC 프로토콜, 외부 웹훅 수신은 각자의 고유 API 계약을 따릅니다.

구성 표면

라우트 구조는 내부 컨트롤러 구현이 아니라 운영자가 실제로 관리하는 도메인 대상을 기준으로 정리되어 있습니다.

프로바이더와 모델 접근

실행 중인 에이전트가 추론을 수행하려면 업스트림 모델 연결이 필요합니다. 운영자는 AIGateway의 프로바이더 관리 라우트와 개별 에이전트의 모델 프로필 라우트를 통해 이를 구성합니다.

메서드 경로 용도
GET /api/v2/site/ai-gateway/provider-kinds 현재 배포 인스턴스에서 구성할 수 있는 프로바이더 종류 목록 조회
GET /api/v2/site/ai-gateway/models Console 설정 화면용 지원 capability가 포함된 프로바이더 모델 목록 조회
GET /api/v2/site/ai-gateway/providers 구성된 프로바이더 목록 조회
GET /api/v2/site/ai-gateway/providers/:provider_id 단일 프로바이더 설정 및 자격 증명 풀 상태 조회
PATCH /api/v2/site/ai-gateway/providers/:provider_id 프로바이더 생성 또는 전체 교체
DELETE /api/v2/site/ai-gateway/providers/:provider_id 프로바이더 삭제
POST /api/v2/site/ai-gateway/providers/:provider_id/credentials 자격 증명 풀에 새 멤버 추가
PATCH /api/v2/site/ai-gateway/providers/:provider_id/credentials/:credential_id 풀 멤버 정보 수정 또는 재인증
DELETE /api/v2/site/ai-gateway/providers/:provider_id/credentials/:credential_id 풀 멤버 제거
PATCH /api/v2/site/ai-gateway/providers/:provider_id/credential-pool/strategy 풀 선택 전략 변경
POST /api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login ChatGPT 디바이스 코드 또는 브라우저 로그인 시작
POST /api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login/poll 진행 중인 디바이스 로그인 완료 여부 폴링
POST /api/v2/site/ai-gateway/providers/:provider_id/chatgpt-login/browser-callback 브라우저 콜백 URL 붙여넣기 폴백 완료
POST /api/v2/site/ai-gateway/providers/:provider_id/chatgpt-enterprise-credentials ChatGPT Enterprise 액세스 토큰 직접 등록
GET /api/v2/model-profiles Pod 또는 사이트 기본 모델 프로필과 provider-hosted 스위치 조회
PUT /api/v2/model-profiles/:profile Pod 또는 사이트 기본 모델 프로필 설정
DELETE /api/v2/model-profiles/:profile Pod 또는 사이트 기본 모델 프로필 제거(?defaults_scope=로 범위 지정)
PUT /api/v2/model-profiles/provider-hosted Pod 또는 사이트 provider-hosted 기능 스위치 설정
GET /api/v2/system-principals 등록된 시스템 서비스 Principal 목록 조회(ankole_brain, system 등)
GET /api/v2/system-principals/:uid/model-profiles 시스템 Principal의 모델 프로필 재정의 및 유효 설정 조회
PUT /api/v2/system-principals/:uid/model-profiles/:profile 시스템 Principal의 고정 슬롯 모델 재정의 설정
DELETE /api/v2/system-principals/:uid/model-profiles/:profile 시스템 Principal 모델 재정의 삭제 및 Pod·사이트 기본값 상속 복원
GET /api/v2/agents/:agent_uid/model-profiles 특정 에이전트의 모델 프로필 재정의, 상속값 및 유효 프로필 조회
PUT /api/v2/agents/:agent_uid/model-profiles/:profile 에이전트 고정 슬롯 재정의 또는 사용자 지정 모델 프로필 설정
DELETE /api/v2/agents/:agent_uid/model-profiles/:profile 에이전트 모델 프로필 재정의 또는 사용자 지정 프로필 삭제
PUT /api/v2/agents/:agent_uid/provider-hosted 단일 에이전트의 provider-hosted 기능 스위치 재정의 설정

모든 프로바이더 자격 증명은 에이전트 컨테이너가 아닌 컨트롤 플레인 내부에 암호화된 풀 멤버로 보관됩니다. 모델 프로필은 사이트 기본값 → Pod 기본값 → 에이전트 또는 시스템 서비스 Principal 재정의(ankole_brain은 Brain 추출·Dreaming·URL 가져오기·리랭크 호출용, system은 내부 작업용) 계층으로 해석되며, 런타임에 AIGateway가 정상 상태인 풀 멤버를 골라 호출합니다. API 응답 프로젝션에는 마스킹된 안전한 계정 정보와 상태(health), 속도 제한 수치, 누적 사용량만 포함됩니다.

Agent와 그 능력

에이전트는 다른 모든 운영 설정이 연결되는 중심 단위입니다.

메서드 경로 용도
GET /api/v2/agents 에이전트 목록 조회
POST /api/v2/agents 새 에이전트 생성
GET /api/v2/agents/:agent_uid 단일 에이전트 상세 조회
PATCH /api/v2/agents/:agent_uid 에이전트 속성 수정
POST /api/v2/agents/:agent_uid/enable 비활성화된 에이전트 다시 활성화
POST /api/v2/agents/:agent_uid/rename 비활성화된 에이전트의 Worker 종료 후 UID 이름 변경
DELETE /api/v2/agents/:agent_uid 활성 에이전트는 비활성화하고, 이미 비활성화된 에이전트는 영구 삭제

Worker 프로바이더

각 Agent는 생성 시점에 사용할 Worker 프로바이더 하나를 선택하며 저장 후에는 다른 프로바이더로 바꿀 수 없습니다. 프로바이더의 YAML 구성과 암호화된 플랫폼 자격 증명은 분리해 저장합니다. 세부 수명 주기와 스토리지 계약은 Worker 관리를 참조하세요.

메서드 경로 용도
GET /api/v2/site/worker-provider-kinds 지원하는 프로바이더 종류, YAML 예시, 필수 자격 증명 항목 조회
GET /api/v2/site/worker-providers 등록된 Worker 프로바이더 목록 조회
POST /api/v2/site/worker-providers 새 Worker 프로바이더 생성
PATCH /api/v2/site/worker-providers/:provider_id 프로바이더 설정 또는 자격 증명 수정
GET /api/v2/site/worker-providers/:provider_id/check 외부 플랫폼 연결 및 권한 점검
DELETE /api/v2/site/worker-providers/:provider_id 어떤 Agent도 참조하지 않는 프로바이더 삭제
PUT /api/v2/agents/:agent_uid/worker-provider 마이그레이션 직후 프로바이더가 미지정된 Agent에 최초 할당

시그널 라우팅 규칙

시그널 라우팅 규칙(API 스키마 명칭 Signal Binding)은 외부 채널 어댑터를 지정된 AI Colleague(ai_colleague 모드)에 연결하거나, 공유 Lark/Feishu 및 Slack Personal Assistant Bot에서 매칭된 발신자 각자의 Personal Assistant(sender_personal_assistant 모드, agent_uid는 null)로 라우팅합니다.

메서드 경로 용도
GET /api/v2/signal-adapters 현재 배포 인스턴스에 선언된 시그널 어댑터 목록 조회
GET /api/v2/signal-bindings 라우팅 규칙 목록 조회(?agent= 쿼리로 특정 Agent 필터링)
GET /api/v2/signal-bindings/:id 단일 라우팅 규칙 조회
PUT /api/v2/signal-bindings/:adapter_id/:binding_name 라우팅 규칙 생성 또는 재활성화
PATCH /api/v2/signal-bindings/:id 라우팅 규칙 수정
DELETE /api/v2/signal-bindings/:id 라우팅 규칙 비활성화
POST /api/v2/agents/:agent_uid/signal-deliveries/requeue 전송 실패한 아웃바운드 시그널 재큐잉
GET /api/v2/conversations/:conversation_id/standing-orders 특정 Conversation의 상시 지시(standing order) 조회
PUT /api/v2/conversations/:conversation_id/standing-orders 특정 Conversation의 상시 지시 전체 교체

바인딩을 비활성화하면 설정 자체를 삭제하지 않고도 해당 채널에서 새 시그널이 에이전트를 깨우지 않도록 일시 차단할 수 있습니다.

Agent Library 능력

라이브러리 기본 활성화 상태는 선택한 테넌트 단위로 저장되며, 개별 Agent 재정의 역시 해당 테넌트 범위 안에서 적용됩니다.

메서드 경로 용도
GET /api/v2/agent-library/capabilities 테넌트의 라이브러리 capability 카탈로그 및 기본값 조회
PUT /api/v2/agent-library/agent-plugins/:id 플러그인의 테넌트 기본 활성화 상태 설정
PUT /api/v2/agent-library/skills/:id 스킬의 테넌트 기본 활성화 상태 설정
GET /api/v2/agents/:agent_uid/library-capabilities 특정 에이전트의 유효 capability 목록 조회
PUT /api/v2/agents/:agent_uid/library-capabilities/agent-plugins/:id 특정 에이전트의 플러그인 활성화 재정의
PUT /api/v2/agents/:agent_uid/library-capabilities/skills/:id 특정 에이전트의 스킬 활성화 재정의
GET /api/v2/agents/:agent_uid/library-documents 에이전트의 영구 라이브러리 문서 목록 조회
GET /api/v2/agents/:agent_uid/skill-lessons 활성 및 폐기된 Skill 교훈 목록 조회
POST /api/v2/agents/:agent_uid/skill-lessons 활성화된 Skill에 운영자 수동 교훈 추가
POST /api/v2/agents/:agent_uid/skill-lessons/:lesson_id/retire 특정 Skill 교훈 폐기

먼저 테넌트 단위에서 기본 구성을 정한 뒤 개별 Agent마다 허용 범위를 좁히거나 넓힐 수 있습니다. Skill 교훈은 원본 SKILL.md를 수정하지 않고 특정 Agent에만 추가 업무 지침을 덧붙이며, 조회 결과에는 근거 기록과 폐기 이력이 함께 포함됩니다. 폐기된 교훈은 실행 시 제공되지 않으며 사람이 직접 폐기한 항목은 Dreaming이 비슷한 내용을 다시 자동 생성하지 않도록 금지 목록에 남습니다. 세부 수명 주기와 한도는 Skill 교훈을 참조하세요.

환경 변수(WorkerEnv)

WorkerEnv는 사이트 기본값, 테넌트 재정의, 개별 Agent 연결의 3단계 계층을 제공합니다. 일반 조회 라우트는 메타데이터만 반환하며, 실제 평문 값은 감사 기록이 남는 전용 복호화(decryptions) 엔드포인트를 호출해야 확인할 수 있습니다.

메서드 경로 용도
GET /api/v2/site/worker-envs 사이트 범위 기본 환경 변수 목록 조회
PUT /api/v2/site/worker-envs/:name 사이트 기본값 설정
DELETE /api/v2/site/worker-envs/:name 사이트 기본값 삭제
POST /api/v2/site/worker-envs/:name/decryptions 사이트 환경 변수 평문 복호화
GET /api/v2/worker-envs 테넌트 범위 환경 변수 목록 조회
PUT /api/v2/worker-envs/:name 테넌트 환경 변수 설정
DELETE /api/v2/worker-envs/:name 테넌트 환경 변수 삭제
POST /api/v2/worker-envs/:name/decryptions 테넌트 환경 변수 평문 복호화
GET /api/v2/agents/:agent_uid/worker-envs 특정 Agent에 연결된 환경 변수 목록 조회
PUT /api/v2/agents/:agent_uid/worker-envs/:name 특정 Agent에 환경 변수 연결 또는 전용 값 재정의
DELETE /api/v2/agents/:agent_uid/worker-envs/:name 특정 Agent의 환경 변수 연결 해제
POST /api/v2/agents/:agent_uid/worker-envs/:name/decryptions 특정 Agent의 환경 변수 평문 복호화

Agent에 연결된 변수는 전용 재정의 값이 있으면 그 값을 우선 사용하고, 없으면 테넌트 값 → 사이트 기본값 순서로 상속합니다. 환경 변수 값은 Worker 작업이 시작될 때 해석되어 주입되며 이미 열려 있는 기존 작업 공간은 처음 생성될 때 받은 환경을 그대로 유지합니다.

Control Plane Plugins

메서드 경로 용도
GET /api/v2/site/control-plane-plugins 설치된 Control Plane Plugins 목록과 활성 상태 조회
PUT /api/v2/site/control-plane-plugins 선택형 플러그인 활성화 또는 비활성화 예약

Control Plane Plugins는 릴리스 컴파일 시점에 함께 포함되는 퍼스트 파티 확장 모듈로서 Signals 어댑터, Identity Provider 어댑터, AI Gateway 프로바이더, Worker 프로바이더 같은 컨트롤 플레인 기능을 추가합니다. activation: :always로 선언된 플러그인은 항상 켜져 있으며, PUT /api/v2/site/control-plane-plugins는 다음 재시작부터 반영될 :optional 플러그인의 활성 여부를 전환합니다. 이때 현재 사용 중인 Worker 프로바이더처럼 활성 리소스가 남아 있는 플러그인이 실수로 꺼지지 않도록 각 서브시스템의 veto_disable 검사를 먼저 수행합니다.

Identity providers와 AppConfiguration

메서드 경로 용도
GET /api/v2/identity-provider-adapters 현재 배포 인스턴스가 지원하는 IdP 어댑터 목록 조회
GET /api/v2/identity-providers 구성된 Identity Provider 목록 조회
PUT /api/v2/identity-providers/:provider_id IdP 생성 또는 교체
POST /api/v2/identity-providers/:provider_id/sync-runs IdP에서 조직 디렉터리 및 그룹 동기화 실행
GET /api/v2/site/app-configurations 사이트 범위 런타임 설정 키 목록 조회
PUT /api/v2/site/app-configurations/:key 사이트 범위 설정값 저장
POST /api/v2/site/app-configurations/:key/decryptions 사이트 범위 암호화 설정 복호화
GET /api/v2/app-configurations 테넌트 범위 런타임 설정 키 목록 조회
PUT /api/v2/app-configurations/:key 테넌트 범위 설정값 저장
POST /api/v2/app-configurations/:key/decryptions 테넌트 범위 암호화 설정 복호화

AppConfiguration은 코드에 선언된 런타임 운영 설정을 사이트 또는 테넌트 범위로 저장합니다. 사이트 키는 /api/v2/site/app-configurations에서, 테넌트 키는 /api/v2/app-configurations에서 다루며 두 경로 모두 목록 조회, 단건 조회, 값 저장, 재정의 초기화, 감사 대상 복호화를 지원합니다. 반면 데이터베이스 접속 정보처럼 부트스트랩 단계에 필요한 비밀 값은 배포 환경 변수나 시크릿 마운트로 주입합니다.

테넌트 관리

메서드 경로 용도
GET /api/v2/site/tenants 전체 테넌트 목록 조회
POST /api/v2/site/tenants 새 테넌트 생성
PATCH /api/v2/site/tenants/:tenant_id 테넌트 속성 수정
DELETE /api/v2/site/tenants/:tenant_id 테넌트 삭제 요청
POST /api/v2/site/tenants/:tenant_id/suspension 테넌트 일시 중지
DELETE /api/v2/site/tenants/:tenant_id/suspension 일시 중지된 테넌트 재개
GET /api/v2/site/privileged-tenant 현재 사이트 관리 권한을 가진 특권 테넌트 조회
PATCH /api/v2/site/privileged-tenant 사이트 관리 특권을 다른 테넌트로 이전

읽기 표면

Console API는 구성 변경뿐 아니라 시스템 전반의 운영 상태를 모니터링하는 조회 통로 역할도 함께 수행합니다. 각 서브시스템의 주요 관측 라우트는 다음과 같습니다.

  • 실행 중인 Agents: /api/v2/agents/:agent_uid/sessions 및 Agent별 cron 스케줄·checkback 조회·관리 라우트(목록 엔드포인트는 테넌트 전체 범위이며 agent 쿼리 필터 지원).
  • Workers: /api/v2/agent-workers에서 각 Agent에 할당된 Worker 인스턴스 상태를 조회합니다.
  • 통합 드라이브(Unified Drive): GET /api/v2/drive/:tenant_id/nodes로 테넌트 루트 및 하위 노드를 조회하고, POST /api/v2/drive/:tenant_id/nodes로 페이지나 빈 파일을 생성하며, PATCH /api/v2/drive/:tenant_id/nodes/:id로 이동·이름 변경, DELETE /api/v2/drive/:tenant_id/nodes/:id로 하위 트리를 휴지통에 보냅니다. 실제 바이트 전송은 네이티브 라우트인 POST /api/v2/drive/:tenant_id/uploads(멀티파트 업로드)와 GET /api/v2/drive/:tenant_id/nodes/:id/content(스트림 다운로드)로 처리하며, 동일한 브라우저 세션·CSRF 검증과 site_console:drive 권한 아래 Worker가 실행 중이지 않아도 동작합니다.
  • Jobs: /api/v2/background-agent-jobs에서 백그라운드 작업의 목록 조회, 상세 확인, 취소를 수행합니다.
  • AI 활동: /api/v2/ai-gateway/conversations에서 AIGateway 대화 목록과 대화별 메시지 이력을 조회합니다.
  • Principals, AuthZ 및 OIDC 클라이언트: /api/v2/principals(POST /api/v2/principals/:uid/rename, PATCH /api/v2/principals/:uid/membership, POST /api/v2/principals/:uid/access-disables, POST /api/v2/principals/:uid/access-restorations 포함), /api/v2/principal-groups, /api/v2/permission-grants, /api/v2/oidc-clients를 통해 조회·관리하며 Principal 및 AuthZ의 권한 모델을 따릅니다.

여기에 없는 것에 대한 참고

외부 인바운드 /webhooks/* 경로는 각 외부 플랫폼이나 capability 토큰 고유의 검증 방식을 사용하며, 런타임 AI 호출 경로인 /api/v1/ai-gateway/*는 AIGateway bearer 토큰 인증을 사용합니다. 본 문서에서 다룬 브라우저 세션 및 CSRF 검증은 /api/v2 관리 라우트에 적용됩니다.

다음 단계