AI-Q Skill은 Claude Code, Codex, OpenCode 같은 범용 에이전트 하네스가 NVIDIA AI-Q 서버에 리서치 작업을 위임하도록 만드는 스킬이다. 하네스는 세션·도구·코드 실행을 관리하고, AI-Q는 검색·계획·종합·인용·평가가 포함된 딥리서치 파이프라인을 담당한다.
왜 필요한가
일반 에이전트 하네스도 웹 검색과 문서 요약은 할 수 있다. 하지만 기업 환경의 딥리서치는 단순 검색보다 복잡하다.
- 내부 데이터 소스 연결
- 인증된 MCP 서버 접근
- 사용자별·서비스별 권한 유지
- 장시간 작업의 비동기 실행
- 출처 추적과 감사 로그
- 리서치 품질 평가
AI-Q Skill은 이 복잡도를 각 하네스가 다시 구현하지 않게 한다. 에이전트는 “조사 보고서를 만들어라”라는 고수준 작업을 AI-Q 서버에 제출하고, 완료된 구조화 보고서를 받는다.
구성 요소
| 구성 | 역할 |
|---|---|
SKILL.md | 하네스가 언제 AI-Q를 사용할지 알려주는 지침 |
scripts/aiq.py | 작업 제출, 라우팅, polling, 결과 회수를 처리하는 helper |
| AI-Q 서버 | intent classification, clarification, shallow/deep research, evaluation 수행 |
| NeMo Agent Toolkit | AI-Q 내부에서 MCP 도구와 리서치 파이프라인을 구성 |
기본 서버 URL은 http://localhost:8000이며, AIQ_SERVER_URL로 바꿀 수 있다.
MCP 인증 패턴
AI-Q의 엔터프라이즈 가치는 MCP 서버를 안전하게 데이터 소스로 붙이는 데 있다.
| 시나리오 | 패턴 |
|---|---|
| 인증 없는 MCP 서버 | mcp_client function group |
| 백엔드 앱 권한으로 접근 | mcp_client + mcp_service_account |
| 사용자 bearer token 전달 | AI-Q tool에서 get_auth_token() 사용 |
특히 장시간 리서치 작업에서는 요청 제출 시점의 사용자 토큰을 Dask worker 안에서 복원해 같은 권한 맥락으로 도구를 호출한다. 다만 토큰을 작업 중간에 refresh하지 못하면 긴 작업에서 만료 리스크가 남는다.
배포 모델
AI-Q Blueprint는 Docker Compose와 Helm chart를 제공한다. 따라서 개발자 노트북, 클라우드 Kubernetes, 온프레미스, air-gapped 환경에 같은 파이프라인을 배포할 수 있다.
규제 산업에서 중요한 점은 다음이다.
- 원본 문서가 통제 환경 밖으로 나가지 않는다.
- Nemotron 계열 오픈 모델을 NIM으로 자체 호스팅할 수 있다.
- OpenTelemetry trace와 출처 기반 보고서로 감사 가능성을 확보한다.
언제 쓰면 좋은가
- 내부 정책, 법무, 금융, 의료 문서에 근거한 장문 리서치 보고서가 필요할 때
- 코딩 에이전트에게 민감한 데이터 원본 접근권을 직접 주고 싶지 않을 때
- 검색·RAG·평가 파이프라인을 팀별로 중복 구현하지 않고 중앙화하고 싶을 때
- agent-skills를 통해 고수준 능력을 하네스에 주입하려는 플랫폼 팀
관련 문서
- agent-skills — 스킬 시스템의 기본 개념
- agent-harness — 모델 외부에서 에이전트 성능을 결정하는 하네스 설계
- deep-research-max — Google의 자율 딥리서치 에이전트
- mcp — 에이전트와 외부 시스템을 연결하는 표준 프로토콜
참고 자료
- Add a Specialized Deep Research Skill to Agent Harnesses — NVIDIA Technical Blog (2026-05-21)