NiCE Cognigy Plugin
각 클라이언트의 네이티브 플러그인 메커니즘을 통해 독점적으로 배포됩니다. 즉, Claude Code, Claude Desktop, ChatGPT + Codex, 그리고 Antigravity용 플러그인이며, Cursor용 플러그인, 그리고 모든 호환 가능한 호스트(예: Kiro, VS Code + Copilot)에서 사용할 수 있는 Agent Plugins 표준 플러그인입니다. 더 많은 클라이언트가 추가될 예정입니다. 각 패키지는 서버 엔진을 설치하고 스킬(skills)과 에이전트(agents)를 함께 제공합니다.
당신의 AI 어시스턴트를 Cognigy.AI REST API에 연결하는 플러그인입니다. 클라이언트에서 벗어나지 않고도 자체 개선 루프(self-improvement loop)를 통해 LLM 기반의 AI 에이전트(Agent)를 생성, 테스트 및 개선할 수 있습니다.
빠른 링크: [설치 (Installation)] · [최신 상태 유지 (Staying up to date)]
기능 (Features)
- 에이전트 생성, 배포, 패키징, 백업, 음성 설정, 그리고 에이전트 간 위임(A2A delegation)을 위한 18가지 워크플로우 도구 제공
- 원클릭 에이전트 설정: Agent + Flow + AI Agent Job Node + REST Endpoint를 자동으로 생성합니다.
- 자체 개선 루프 (Self-improvement loop): 에이전트와 대화하고, 응답을 평가하며, 작업 설명(job description)을 업데이트하는 과정을 반복할 수 있습니다.
- 지식 저장소 지원: RAG 지식 저장소를 도구로 에이전트에 연결할 수 있습니다.
- 브라우저 음성 배포: WebRTC 데모 URL과 함께 Voice Gateway 엔드포인트를 생성합니다.
- 음성 미리보기 설정: 음성 경험을 위해 지원되는 음성 제공업체(speech providers)를 구성합니다.
- 스킬 + 에이전트: 워크플로우 가이드가 지원 클라이언트의 스킬로 자동 로드되며; 빌드/실행 루프는 서브에이전트로 실행됩니다.
- 내장 문서 조회 (Built-in docs lookup): 공식 Cognigy documentation MCP 서버를 번들링합니다. 사용자의 어시스턴트가 플랫폼 질문에 추측하는 대신, 문서를 검색하고 읽은 후 답변합니다.
- 내장된 속도 제한(rate limiting), Zod 입력 유효성 검사(input validation), 그리고 RFC 7807 오류 응답 기능을 제공합니다.
설치 (Installation)
두 단계로 진행됩니다. 1단계는 모든 고객사(클라이언트)에게 동일합니다. 2단계에서는 고객사가 아직 당신으로부터 무엇을 더 필요로 하는지 확인해야 합니다. 대부분의 클라이언트는 아무것도 필요하지 않지만, 답은 표에 있으니 추측하기보다는 반드시 해당 고객사를 찾아보세요.
1단계 — 설치 프로그램 실행
하나의 설치 프로그램이 모든 고객사를 포괄합니다. 이를 실행하고, 사용할 고객사(클라이언트)를 선택한 다음, Cognigy API 기본 URL을 입력하고 (평가판 기본값 사용 시 'Enter' 누름), API 키를 입력합니다 (입력하는 동안 마스킹됨). 그런 다음 클라이언트를 재시작하세요.
macOS / Linux — 한 줄 명령어(Node.js를 확인한 후 설치 프로그램을 실행):
bash <(curl -fsSL https://raw.githubusercontent.com/Cognigy/cognigy-plugin/main/install.sh)
Windows (PowerShell) — 관리자 권한으로 열고 다음을 실행하세요:
irms://raw.githubusercontent.com/Cognigy/cognigy-plugin/main/install.ps1 | iex
부트스트랩(bootstrap)은 Node.js 20+가 존재하는지 여부만 확인합니다 (설치 방법을 알려주지만, 직접 설치해주지는 않습니다). 그런 다음 정확히 아래 명령어를 실행합니다. 선호하는 것을 사용하세요. 둘 다 같은 역할을 합니다.
이미 Node.js 20+를 가지고 있나요? 부트스트랩을 건너뛰세요:
npx -y -p @cognigy/plugin-engine@latest cognigy-setup
2단계 — 고객사(클라이언트) 행 확인
설치 프로그램이 모든 곳에 자격 증명(credentials)을 연결하고 플러그인을 설치할 수 있는 모든 곳에 설치하지만, 일부 고객사는 당신의 수동 작업이 필요한 단계가 있습니다. 아래에서 해당 고객사를 찾아보고 설치 프로그램 후 추가 단계에 명시된 대로 진행하세요. **'없음(None)'**은 1단계로 작업이 완료되었음을 의미합니다. 각 가이드에는 전체 지침, Windows 관련 참고 사항, 작동 여부 확인 방법 및 문제 해결 방법이 포함되어 있습니다.
Cursor는 설치 프로그램 자체가 전혀 필요 없는 유일한 고객사입니다. 이 클라이언트는 자격 증명을 자체적으로 수집하므로, 해당 가이드에서 시작하여 1단계를 건너뛸 수 있습니다.
| 클라이언트 | 도구 | 스킬 | 에이전트 | 설치 후 추가 단계 | 자동 업데이트 |
|---|
| Claude Code (CLI 및 데스크톱 "Code" 탭) | ✅ | ✅ | ✅ | 없음 | 한 번 활성화 <sup>1</sup> |
| ... | | | | | |
<sup>1</sup> Claude Code는 서드파티 마켓플레이스에서 자동 업데이트를 비활성화하므로, /plugin → Marketplaces → cognigy-plugin에서 한 번 켜야 합니다.<br><sup>2</sup> Cursor는 자격 증명을 자체적으로 요청합니다(Plugins → Configure). 따라서 설치 프로그램이 필요하지 않습니다. 가이드 참조.<br><sup>3</sup> 호스트가 플러그인 버전을 소유합니다. | | | | | |
<details>
<summary>스크립팅 / CI (지속적 통합)</summary>
플래그를 사용하여 프롬프트를 건너뛰기:
npx -y -p @cognigy/plugin-engine@latest cognigy-setup \
--client claude-code --client claude-desktop --client codex \
--client antigravity --client other-hosts \
...
--client는 반복 가능하며, 유효 값은 claude-code, claude-desktop, codex, antigravity, 및 other-hosts입니다. 메뉴에서 선택하려면 생략하십시오.
</details>
최신 상태 유지하기
위의 표에서 각 클라이언트가 자체적으로 수행하는 작업을 확인하십시오. 클라이언트가 감지하기를 기다리는 대신 지금 새 릴리스를 가져오려면:
npx -y -p @cognigy/plugin-engine@latest cognigy-setup update
이 설치 프로그램은 관리자 역할도 수행합니다:
npx -y -p @cognigy/plugin-engine@latest cognigy-setup status # 어떤 클라이언트가 무엇을 설치했는지, 그리고 최신 사용 가능 버전 확인
npx -y -p @cognigy/plugin-engine@latest cognigy-setup update # 자동 업데이트되지 않은 곳의 최신 버전을 가져옵니다
npx -y -p @cognigy/plugin-engine@latest cognigy-setup uninstall # 모든 클라이언트에서 제거합니다 (--client로 범위를 좁힐 수 있습니다; --purge는 ~/.cognigy-plugin도 지웁니다)
MCP 도구 외에도 이 플러그인은 워크플로우를 자동으로 노출하는 **스킬(skills)**과 **에이전트(agents)**를 제공합니다:
- 스킬 (Skills) (
/skills) — 워크플로우별로 하나씩 존재합니다 (에이전트 생성, 지식/RAG, 음성 게이트웨이, 음성 Go-Live 체크리스트, 웹채팅, 플로우 노드, 패키지, 설정, LLM 제공업체, 도구, 레드팀(red-teaming), 문제 해결). Claude는 요청 내용에 맞는 스킬을 자동으로 로드합니다. 레드팀은 서브 에이전트가 아닌 메인 세션에서 실행되므로 범위 계약에 합의하고, 수정 사항 적용 전에 승인을 받고, 최종 보고서를 열어줄 수 있습니다.
- 에이전트 (Agents) (
/agents) — cognigy-agent-builder는 새로운 에이전트에 대한 전체 빌드 및 테스트 루프를 실행하며, cognigy-voice-go-live는 음성 에이전트를 Go-Live 체크리스트와 비교하여 감사하고 안전한 수정 사항을 적용합니다. 각각은 자체 컨텍스트에서 실행되며 요약 보고서를 반환합니다.
설정 (Configuration)
설치기는 Cognigy API 기본 URL과 API 키를 수집하여 클라이언트별로 연결합니다: Claude Code에서는 시스템 **키체인(keychain)**에, Claude Desktop에서는 claude_desktop_config.json (chmod 600) 파일에 저장됩니다. 엔진은 이를 환경 변수(environment variables)로 받습니다. 특정 실행 시 둘 중 하나라도 누락된 경우, 엔진은 ~/.cognigy-plugin/config.json (chmod 600)으로 폴백(fallback)하며, 설치기 또한 이 파일을 작성합니다. 따라서 자격 증명은 환경 변수에서 먼저 해결되고, 그 다음 파일에서 해결됩니다.
ChatGPT + Codex, Antigravity 및 기타 호스트는 오직 해당 파일에 의존합니다: 이들의 클라이언트 설정에는 비밀 정보가 포함되어 있지 않습니다.
펼쳐지지 않은 ${...} 플레이스홀더 형태로 도착하는 값은 누락된 것으로 간주됩니다. Claude Code를 제외한 다른 호스트들은 userConfig를 구현하지 않으며, 매니페스트의 ${user_config.cognigy_api_key}를 문자 그대로 전달합니다. 이를 실제 자격 증명으로 취급하면 요청이 실패할 뿐만 아니라 파일 폴백을 가릴 수 있습니다. 아래의 선택적 변수들은 기본값을 재정의해야 할 경우 MCP 서버 env에서 설정할 수 있습니다.
| Variable | 필수 여부 | 기본값 | 설명 |
|---|
COGNIGY_API_BASE_URL | Yes | — | Cognigy API의 기본 URL |
| ... | | | |
감사 추적 (Audit attribution)
이 플러그인이 변경하는 모든 내용은 **관리자 센터(Admin Center) → 감사 이벤트(Audit Events)**에 performedBy.actor = "mcp-plugin"으로 기록됩니다. 따라서 플러그인에 의해 발생한 변경 사항은 사람이 수동으로 만든 변경 사항(어떤 performedBy도 포함하지 않음)과 구별할 수 있습니다. 각 MCP 도구 호출은 자체적인 taskId를 얻고, 각 엔진 실행은 자체적인 sessionId를 갖기 때문에, 하나의 도구 호출 기록이 그룹화되어 쓰여집니다.
Cognigy.AI 2026.17.0 이상 버전이 필요합니다. 이전 버전에서는 감사 추적을 무시하고 일반적으로 작업을 기록합니다. UI의 "Performed by" 열은 플랫폼의 FEATURE_ENABLE_PLATFORM_AGENT_MFE 플래그에 의해 제한되지만, 감사 추적은 항상 기록되며 list_resources { resourceType: "audit_event", actor: ["mcp-plugin"] }를 통해 항상 읽을 수 있습니다.
플러그인 동작에서 제외하려면 COGNIGY_DISABLE_AUDIT_ATTRIBUTION=1로 설정하십시오. 그러면 플러그인 작업은 다른 모든 API 작업과 마찬가지로 기록됩니다.
기업 프록시 (Corporate proxies)
네트워크에서 프록시가 필요한 경우, MCP 서버의 env 블록에 설정하거나 클라이언트를 시작하기 전에 환경 변수로 내보내면 됩니다. 그러면 플러그인이 모든 Cognigy 요청을 해당 프록시를 통해 터널링합니다:
"env": {
"HTTPS_PROXY": "http://proxy.corp.example:8080",
"NO_PROXY": "localhost,127.0.0.1",
...
}
소문자 철자(https_proxy)도 작동하며, URL에 자격 증명(credentials)을 포함하는 것도 가능합니다 (http://user:[email protected]:8080). HTTP 및 HTTPS 프록시가 지원되며, SOCKS 프록시는 지원되지 않습니다.
프록시는 요청별로 선택되므로, NO_PROXY를 사용하여 특정 호스트는 제외할 수 있지만 다른 호스트는 여전히 프록시를 통해 전송됩니다. 예를 들어, 패키지 다운로드 링크는 API 호스트가 아닌 플랫폼이 아카이브를 스테이징한 곳을 가리킵니다.
프록시가 구성되었으나 사용될 수 없는 경우(잘못된 URL 또는 SOCKS 프록시 등), 요청은 API 키를 승인된 경로 밖으로 전송하는 직접 연결을 조용히 시도하기보다는 구성 오류로 실패합니다. 정말로 직접 연결을 원한다면 NO_PROXY를 사용하여 해당 호스트를 제외하십시오.
연결을 수락한 후 터널링을 완료하지 않는 프록시는 도구 호출(tool call)을 무기한으로 대기 상태에 빠뜨릴 수 있으므로, 연결 및 협상 과정은 30초로 제한됩니다. 만약 프록시가 단순히 느린 경우라면 COGNIGY_PROXY_CONNECT_TIMEOUT_MS를 높이십시오.
프록시가 TLS를 검사하는 경우 (Zscaler, Netskope, BlueCoat 및 유사 서비스), 해당 프록시는 기본적으로 Node가 신뢰하지 않는 기업 루트 CA(Corporate root CA)로 서명된 자체 인증서를 제시합니다. 이 CA 파일의 경로를 NODE_EXTRA_CA_CERTS에 지정하십시오. Node는 시작 시에만 이를 읽으므로, 이후 클라이언트를 재시작해야 합니다. 대신 절대 NODE_TLS_REJECT_UNAUTHORIZED=0을 설정하지 마십시오. 이는 엔진이 수행하는 모든 연결의 인증서 검증을 비활성화합니다.
엔진이 설정을 올바르게 인식했는지 확인하려면 LOG_LEVEL=debug로 설정하고 클라이언트의 MCP 로그에서 Cognigy API requests route through a proxy를 찾으십시오. GUI 클라이언트(Claude Desktop, Antigravity)는 최소 환경으로 엔진을 시작하며 종종 셸의 프록시 변수를 상속받지 못하므로, 셸 프로필 대신 구성 파일에 설정하십시오.
자체 호스팅 및 로컬 클러스터
엔진은 여러 개의 Cognigy 호스트와 통신합니다. 모든 기능을 위한 API, talk_to_agent용 엔드포인트 호스트, 그리고 임베드 스니펫을 위한 웹챗 및 정적(static) 호스트가 그것입니다. 나머지 세 가지는 COGNIGY_API_BASE_URL에서 api 세그먼트를 교체하여 파생됩니다. 예를 들어, api-dev.cognigy.ai는 endpoint-dev.cognigy.ai를 제공하고, cognigy-api-na1.nicecxone.com은 cognigy-endpoint-na1.nicecxone.com을 제공하며, 로컬 클러스터의 api.test는 endpoint.test를 제공합니다. 만약 호스트 이름이 이러한 패턴을 따르지 않는다면, COGNIGY_ENDPOINT_BASE_URL, COGNIGY_WEBCHAT_BASE_URL, 그리고 COGNIGY_STATIC_FILES_BASE_URL을 명시적으로 설정해야 합니다. 엔진은 API 호스트로 폴백(fallback) 해야 할 경우 시작 시 경고 메시지(Could not derive the endpoint host)를 표시합니다.
셀프 서명 인증서(self-signed certificate)를 제공하는 클러스터는 Node가 운영체제 트러스트 스토어(operating-system trust store)를 참조하지 않기 때문에 DEPTH_ZERO_SELF_SIGNED_CERT 오류와 함께 거부됩니다. 이 경우, NODE_EXTRA_CA_CERTS를 인증서(또는 이를 발급한 로컬 CA)로 지정해야 하며, 이는 위에서 설명된 TLS-inspecting proxy 설정과 동일합니다.
사용 예시
1. 고객 지원 에이전트 생성
Create a Cognigy AI Agent called "Support Bot" in project <projectId> with a helpful customer support persona. If the project has no working LLM, first look for another project with an llm_model that has a connectionId, import that LLM and its connection...
MCP 서버는 먼저 대상 프로젝트에 이미 작동하는 LLM(Large Language Model)이 있는지 확인해야 합니다. 그렇지 않다면, manage_packages를 통해 다른 프로젝트의 필수 LLM 리소스 세트와 연결 리소스를 재사용하는 것을 선호하고, create_ai_agent를 호출하기 직전에 최후 수단으로만 setup_llm을 사용해야 합니다.
2. 에이전트 테스트 및 개선
Talk to my Support Bot at <endpointUrl> and ask "How do I reset my password?".
Then update the job description to make the response more concise and actionable.
Talk to it again and compare the responses.