@bluedus/aiplug-sdk

AIPlug Enterprise AI Agent Platform JavaScript/React SDK

설치

npm install @bluedus/aiplug-sdk

사용법

1. React 컴포넌트 (AgentChat)

가장 빠른 방법 — 컴포넌트 하나로 완전한 채팅 UI를 임베드합니다. Tool 실행 확인, Guardrail 동의, 오케스트레이션 확인, 이미지·차트·테이블 렌더링이 자동으로 처리됩니다.

import { AgentChat } from '@bluedus/aiplug-sdk/react';

export default function App() {
  return (
    <AgentChat
      baseUrl="https://aiplug.yourcompany.com"
      publicKey="your-public-key"
      tenantId="your-tenant-id"
      agentId="your-agent-id"           // null이면 자동 선택
      userId="user-123"
      title="사내 AI 어시스턴트"
      welcomeMessage="안녕하세요! 무엇을 도와드릴까요?"
      dark={true}
      showSources={true}
      showToolCalls={true}
      height="600px"
      width="420px"
    />
  );
}

2. React Hook (useAIPlug)

UI를 직접 구성할 때 사용합니다. Confirm 흐름, ContentBlock 렌더링도 직접 핸들링 가능합니다.

import { useAIPlug } from '@bluedus/aiplug-sdk/react';

function MyChat() {
  const {
    messages,
    isLoading,
    activeToolCall,
    pendingState,      // Tool/Orchestration/Consent 확인 대기 상태
    sendMessage,
    confirm,           // Tool 실행 확인 응답
    acceptConsent,     // Guardrail 동의 응답
    clearHistory,
  } = useAIPlug({
    baseUrl:   'https://aiplug.yourcompany.com',
    publicKey: 'your-public-key',
    tenantId:  'your-tenant-id',
    agentId:   'your-agent-id',
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <span>{msg.role === 'user' ? '나' : 'AI'}</span>

          {/* contents가 있으면 타입별 렌더링, 없으면 텍스트 */}
          {msg.contents?.length ? (
            msg.contents.map((block, i) => {
              if (block.type === 'TEXT')  return <p key={i}>{block.text}</p>;
              if (block.type === 'IMAGE') return <img key={i} src={block.url} alt={block.altText} />;
              if (block.type === 'CHART') return <div key={i}>{/* 차트 렌더러 */}</div>;
              if (block.type === 'TABLE') return <table key={i}>{/* 테이블 렌더러 */}</table>;
            })
          ) : (
            <p>{msg.content}</p>
          )}

          {/* Tool / Orchestration 확인 버튼 */}
          {msg.pending?.type !== 'CONSENT' && msg.pending && (
            <div>
              <button onClick={() => confirm('APPROVED')}>진행</button>
              <button onClick={() => confirm('SKIP')}>건너뛰기</button>
              <button onClick={() => confirm('REJECTED')}>취소</button>
            </div>
          )}

          {/* Guardrail 동의 버튼 */}
          {msg.pending?.type === 'CONSENT' && (
            <div>
              <button onClick={() => acceptConsent(true)}>동의</button>
              <button onClick={() => acceptConsent(false)}>거절</button>
            </div>
          )}
        </div>
      ))}

      {activeToolCall && <p>⚙️ {activeToolCall.toolName} 실행 중...</p>}
      {isLoading && <p>생각 중...</p>}

      <button onClick={() => sendMessage('안녕하세요')} disabled={isLoading}>
        전송
      </button>
    </div>
  );
}

3. Vanilla JS (프레임워크 없음)

import { ChatSession } from '@bluedus/aiplug-sdk';

const session = new ChatSession({
  baseUrl:   'https://aiplug.yourcompany.com',
  publicKey: 'your-public-key',
  tenantId:  'your-tenant-id',
  agentId:   'your-agent-id',
});

await session.send('만기 계약 목록 조회해줘', {
  onPending: (state, conversationId) => {
    console.log('확인 필요:', state.type, state.message);
    // state.type: 'TOOL_CONFIRM' | 'ORCHESTRATION_CONFIRM' | 'CONSENT'
  },
  onComplete: (res) => {
    console.log('텍스트 응답:', res.content);

    // Platform Tool 실행 결과 (이미지·차트·테이블)
    res.contents?.forEach(block => {
      if (block.type === 'IMAGE') console.log('이미지 URL:', block.url);
      if (block.type === 'CHART') console.log('차트 스펙:', block.spec);
      if (block.type === 'TABLE') console.log('테이블 데이터:', block.rows);
    });
  },
  onError: (err) => console.error('에러:', err.message),
});

Platform 내장 기능 (ContentBlock)

에이전트나 Tool을 별도로 설정하지 않아도 모든 대화에서 사용할 수 있는 AIPlug 내장 기능입니다. LLM이 사용자 요청을 판단해 자동으로 실행하며, 결과는 contents 배열로 반환됩니다.

| 기능 | 트리거 예시 | ContentBlock 타입 | |------|------------|------------------| | 이미지 생성 | "퉁퉁이 캐릭터 그려줘", "로고 이미지 만들어줘" | IMAGE | | 차트 시각화 | "월별 매출 차트로 보여줘", "비율 파이차트로" | CHART | | 표 렌더링 | "결과를 표로 정리해줘" | TABLE |

ContentBlock 타입 정의

type ContentBlock =
  | { type: 'TEXT';  text: string }
  | { type: 'IMAGE'; url: string; mimeType: string; altText: string }
  | { type: 'CHART'; chartType: 'bar' | 'line' | 'pie' | 'scatter'; title: string; spec: object }
  | { type: 'TABLE'; title: string; headers: string[]; rows: string[][] }

AgentChat 컴포넌트를 사용하면 이미지·차트·테이블이 채팅 버블 안에 자동으로 렌더링됩니다. useAIPlug Hook을 사용하면 msg.contents로 직접 접근해 커스텀 렌더러를 적용할 수 있습니다.

Confirm 흐름

HIGH/MEDIUM 위험 Tool 실행 또는 Guardrail이 설정된 Agent 사용 시 사용자 확인을 요청합니다.

사용자 메시지 전송
    ↓
서버: PENDING_TOOL_CONFIRM 응답
    ↓
SDK: pendingState 세팅 + 확인 버튼 표시
    ↓
사용자: 진행 / 건너뛰기 / 취소 클릭
    ↓
SDK: confirmAction 포함 재요청
    ↓
서버: 실행 재개 → 최종 응답

Props 참조 (AgentChat)

| Prop | 타입 | 기본값 | 설명 | |------|------|--------|------| | baseUrl | string | 필수 | AIPlug Core 서버 URL | | publicKey | string | 필수 | 테넌트 Public Key | | tenantId | string | 필수 | 테넌트 ID | | agentId | string \| null | null | Agent ID (null이면 자동 선택) | | userId | string \| null | null | 사용자 식별자 (로그용) | | title | string | 'AI Agent' | 헤더 타이틀 | | placeholder | string | '메시지를 입력하세요...' | 입력창 placeholder | | welcomeMessage | string | — | 첫 안내 메시지 | | height | string | '560px' | 컴포넌트 높이 | | width | string | '400px' | 컴포넌트 너비 | | dark | boolean | false | 다크 테마 | | showSources | boolean | true | RAG 출처 표시 | | showToolCalls | boolean | true | Tool 실행 상태 표시 | | streaming | boolean | true | SSE 스트리밍 사용 여부 (false이면 V2 동기 방식) |

버전 이력

| 버전 | 변경 내용 | |------|-----------| | 0.1.7 | Phase 진행 상태 표시 추가 — 스트리밍 중 Agent 탐색·RAG 검색·Tool 실행 등 처리 단계 실시간 표시. thinkingStep 상태 추가. onThinking 콜백 추가. | | 0.1.6 | SSE 스트리밍 추가 — /api/v3/chat 연동. 토큰 실시간 렌더링. isStreaming 상태, streaming 옵션 추가. streamMessage() API 추가. | | 0.1.5 | 서버 에러 메시지 반환 추가 | | 0.1.4 | 타입 에러 수정. | | 0.1.3 | Platform 내장 기능 추가 — 이미지 생성·차트·테이블 ContentBlock 자동 렌더링. AgentResponse.contents, UIMessage.contents 타입 추가. | | 0.1.2 | Confirm 흐름 추가 — PENDING_TOOL_CONFIRM, PENDING_ORCHESTRATION_CONFIRM, PENDING_CONSENT 자동 처리. /api/v2/chat 전환. confirmAction, agentAccepted 파라미터 지원. | | 0.1.1 | 버그 수정 | | 0.1.0 | 최초 릴리즈 |

배포 (GitLab CI)

# 버전 태그 push → npm 자동 배포
git tag v0.1.3
git push origin v0.1.3

GitLab CI/CD Variables에 NPM_TOKEN 등록 필요.

라이선스

UNLICENSED — ㈜블루더스 내부용