PiGNiTO AI Agent SDK

한눈에 보기

PiGNiTO SDK는 외부 웹사이트에 AI 업무 에이전트를 삽입하는 JavaScript 라이브러리입니다. 단순 Q&A 챗봇이 아니라, 자동화 실행·승인·결과 전달까지 처리하는 에이전트 UI를 제공합니다.

설치는 CSS/JS 파일 로드와 Access Key 한 줄이 전부입니다. 에이전트의 구성과 표시 방식은 PiGNiTO 콘솔에서 설정하고, 개발자는 Key만 웹사이트에 넣으면 됩니다.

관리자 설정

SDK를 설치하기 전에 PiGNiTO 콘솔에서 에이전트를 구성합니다. 이 단계는 개발자가 아닌 관리자가 수행합니다.

에이전트 구성

콘솔에서 에이전트의 스킬·자동화·이미지를 설정합니다. 하나의 Access Key에 에이전트 하나가 연결되며, SDK를 통해 방문자에게 그 에이전트가 노출됩니다.

위젯 설정

SDK가 표시될 방식(표시 방식, 버튼 노출 여부, 에이전트 이름·이미지 등)을 콘솔에서 설정합니다. 이 설정은 SDK가 초기화될 때 서버에서 자동으로 내려갑니다. 개발자가 코드에 표시 방식을 명시하지 않으면 콘솔 설정이 그대로 적용됩니다.

Access Key 발급

에이전트 설정 완료 후 콘솔에서 Access Key를 발급합니다. 키는 pig-로 시작합니다. 이 키를 개발자에게 전달합니다.

웹사이트 설치

관리자에게 받은 Access Key를 웹사이트에 붙이면 됩니다.

기본 설치

</body> 직전 또는 </head> 안에 아래 코드를 추가합니다. 표시 방식은 콘솔 설정을 따릅니다.

<!-- SDK 에셋 -->
<link rel="stylesheet" href="https://your-domain.com/sdk/pignito.css">
<script src="https://your-domain.com/sdk/pignito-script.js"></script>

<!-- Access Key -->
<script>
  Pignito.init('pig-xxxxxxxxxxxx');
</script>

설치 후 확인

정상 설치 시 우하단에 플로팅 버튼(FAB)이 나타납니다. 버튼을 클릭하면 에이전트 패널이 열립니다. 버튼이 보이지 않으면 문제 해결 섹션을 참고하세요.

특정 버튼으로 열기

FAB 버튼을 숨기고 고객사 버튼에서 직접 에이전트를 열 수 있습니다.

Pignito.init('pig-xxxxxxxxxxxx', { fab: false });

// 버튼 클릭 이벤트에서 직접 열기
document.getElementById('my-btn').onclick = function() {
  Pignito.chatOpen();
};

→ 인라인(특정 영역 내 삽입)은 Section 4 참조.

표시 방식

에이전트가 화면에 어떻게 나타나는지는 관리자 콘솔의 위젯 설정에서 결정합니다. 개발자가 코드에서 선택하는 항목이 아닙니다.

관리자가 콘솔에서 아래 4가지 중 하나를 지정하면, SDK는 Pignito.init('pig-xxx') 시 서버에서 그 설정을 받아 그대로 렌더링합니다. 웹사이트 코드는 Access Key만 넣으면 됩니다.

예외: 페이지 안에 직접 삽입 (Inline)

특정 페이지 안에 에이전트 영역을 박아 넣어야 할 때만 코드에서 target 옵션을 지정합니다. 이 경우 콘솔 위젯 설정과 무관하게 해당 요소 안에 인라인으로 마운트됩니다.

Pignito.init('pig-xxx', { target: '#agent-area' });

동작 흐름

Pignito.init()이 호출될 때 내부에서 일어나는 일입니다.

1. 1
   서버에서 에이전트 설정 조회 Access Key로 GET /sdk/api/init를 요청합니다. Key 검증, SubAgent 목록, 위젯 설정이 반환됩니다.
2. 2
   설정 적용 콘솔 위젯 설정(표시 방식·에이전트 이름·이미지 등)을 적용합니다. 코드에서 target·fab·baseUrl 같은 통합 옵션을 명시한 경우 그 값으로 덮어씁니다.
3. 3
   UI 렌더링 콘솔에서 설정한 표시 방식에 따라 에이전트 패널을 DOM에 마운트합니다. FAB 버튼, 드래그·리사이즈 이벤트를 바인딩합니다.
4. 4
   사용 준비 완료 Promise가 resolve됩니다. 이후 Pignito.send() 등의 API를 호출할 수 있습니다.

사용자가 에이전트를 사용할 때

사용자가 채팅 입력 시 SDK가 POST /sdk/api/mcp/execute-stream으로 실행 요청을 보냅니다. 서버가 SubAgent를 실행하고 결과를 스트리밍으로 돌려주면, SDK가 실시간으로 화면에 출력합니다. 자동화가 승인을 요구하면 패널 안에 승인 버튼이 표시됩니다. (chatbot 표시 방식은 대신 단순화된 POST /sdk/api/chat/stream을 사용합니다.)

운영 전 체크리스트

배포 전 확인할 항목입니다.

• ✓
  Access Key 발급 확인 — PiGNiTO 콘솔에서 Key가 활성 상태인지 확인합니다.
• ✓
  Access Key 노출 주의 — 현재 SDK API는 모든 도메인에서 CORS를 허용하며 별도 도메인 제한 기능은 없습니다. Key가 유일한 접근 제어 수단이므로 유출되지 않도록 관리하세요.
• ✓
  SDK 에셋 경로 확인 — pignito.css와 pignito-script.js가 실제로 접근 가능한지 브라우저 Network 탭에서 확인합니다.
• ✓
  관리자가 팝업 표시 방식을 설정한 경우 — chatOpen()을 버튼 클릭 핸들러 내에서만 호출하는지 확인합니다. 비동기 컨텍스트 내 호출은 브라우저가 차단합니다.
• ✓
  SPA 환경 — 라우팅 이동 시 Pignito.destroy() 후 재마운트하거나, init()을 다시 호출하면 자동 정리됩니다.
• ✓
  SDK Lab으로 smoke test — 실제 Key를 SDK Lab에 입력해 init, 채팅 동작을 미리 확인합니다.

문제 해결

자주 발생하는 문제와 원인, 대응 방법입니다.

SDK Lab에서 테스트하기

배포 전 Access Key를 입력해 SDK 동작을 브라우저에서 직접 확인할 수 있습니다.

Access Key를 입력하면 SDK가 즉시 초기화됩니다. FAB/플로팅 모드와 인라인 임베드 모드를 전환하며 UI를 확인할 수 있습니다. 실제 Key로 smoke test를 완료한 후 배포하세요.

개발자 상세 참고

이 섹션은 SDK를 더 세밀하게 제어해야 하는 개발자를 위한 참고 자료입니다. 일반적인 설치에는 위 가이드만으로 충분합니다.

// 방식 1: Key 문자열 + 옵션 객체
Pignito.init('pig-xxx', { fab: false });

// 방식 2: 옵션 객체에 accessKey 포함
Pignito.init({ accessKey: 'pig-xxx', target: '#agent-area' });

{ "success": true, "config": { ... }, "subAgents": [{ "subAgentIdx": 1, "name": "..." }] }

{ "accessKey": "pig-xxx", "subAgentIdx": 1, "userMessage": "..." }

event: done               → { success, result, message? }  최종 응답
event: result             → { result }  중간/최종 응답 (chatbot surface 호환)
event: error              → { message }  실행 오류
event: needs-input        → { question, confirmationMessage }  사용자 입력 필요
event: paused             → 승인 대기 (BEFORE_STEP / approval-required와 동일 처리)
event: approval-required  → 승인 대기 (paused 별칭)