소비자용 AI가 강력한 성능을 발휘하는 것과 달리, 업무용 도구들은 파편화된 데이터와 제한적인 문맥으로 인해 어려움을 겪는 경우가 많습니다. LangChain으로 구축된 NVIDIA AI-Q 블루프린트는 이러한 간극을 메우는 오픈 소스 템플릿으로 주목받고 있습니다. 최근 LangChain은 확장 가능하고 즉시 상용화가 가능한 에이전트 개발을 지원하고자 NVIDIA AI 기반의 엔터프라이즈 에이전트 플랫폼을 공개했습니다.
NVIDIA 런처블(launchable)로 제공되는 이번 튜토리얼은 개발자가 AI-Q 블루프린트를 활용해 고성능 딥 리서치 에이전트를 구축하고, 이를 기업 시스템에 연결하는 방법을 소개합니다. 이 블루프린트는 오픈 소스와 프런티어 LLM을 결합하고, NVIDIA NeMo Agent Toolkit으로 최적화하며 LangSmith를 통해 실행을 모니터링합니다. 결과적으로 기업은 데이터를 안전한 환경에 유지하면서, 에이전틱 검색 애플리케이션 개발 시간을 크게 줄일 수 있습니다.
NVIDIA AI-Q 블루프린트와 NeMo Agent Toolkit은 NVIDIA Agent Toolkit의 일부입니다. 이 플랫폼은 장시간 자율적으로 작동하는 에이전트를 구축, 평가, 최적화할 수 있도록 도구, 모델, 런타임을 통합해 제공합니다.
구축 대상: 딥 에이전트
이번 가이드를 통해 다음과 같은 핵심 역량을 습득하실 수 있습니다.
- 기업용 검색 사례를 위해 LangChain과 결합된 NVIDIA AI-Q 블루프린트를 배포하는 방법
- Nemotron 및 프런티어 LLM을 활용하여 섈로(Shallow) 및 딥 리서치 에이전트를 구성하는 프로세스
- LangSmith와 NVIDIA 도구를 활용해 에이전트의 실행 경로(Trace)와 성능을 모니터링하는 방법
- NeMo Agent Toolkit을 통해 기업 내부 데이터 소스를 연결하는 방법
사전 준비 사항
- NVIDIA API Key: Nemotron 3 등 NVIDIA 호스팅 모델 접근에 필요
- OpenAI API Key: GPT-5.2 등 프런티어 모델 사용 시 필요
- Tavily API Key: 웹 검색 기능 활성화
- Python
- Docker Compose
- (선택 사항) LangSmith: 실험 추적 및 모니터링
NVIDIA와 LangChain을 활용한 장시간 작동 데이터 에이전트 구축 방법
블루프린트 설치 및 실행
먼저 리포지토리를 복제한 후 API 키를 설정하세요. 환경 변수 템플릿을 복사하는 작업부터 시작합니다.
cp deploy/.env.example deploy/.env
이어서 deploy/.env 파일을 열어 필요한 값을 입력합니다.
# Required
NVIDIA_API_KEY=nvapi-...
TAVILY_API_KEY=tvly-...
# Optional: enables trace monitoring (covered later in this post)
LANGSMITH_API_KEY=lsv2-...
NVIDIA_API_KEY는 Nemotron 3 Nano와 같은 NVIDIA 호스팅 모델에 대한 접근 권한을 부여하며, TAVILY_API_KEY는 웹 검색 기능을 활성화합니다.
다음으로 전체 스택을 빌드하고 실행하세요. 여러 컨테이너를 동시에 시작하므로, 인터넷 연결 상태나 하드웨어 사양에 따라 첫 빌드에는 수 분이 소요될 수 있습니다.
docker compose -f deploy/compose/docker-compose.yaml up --build
해당 명령어를 실행하면 다음 세 가지 서비스가 구동됩니다.
- aiq-research-assistant: 8000번 포트에서 작동하는 FastAPI 백엔드
- postgres: 비동기 작업 상태 및 대화 체크포인트를 관리하는 PostgreSQL 16
- frontend: 3000번 포트 기반의 Next.js 웹 UI
모든 서비스가 정상(Healthy) 상태로 확인되면 http://localhost:3000에 접속하세요. 아래 그림 1은 AI-Q Research Assistant의 채팅 인터페이스를 보여주며, 이곳에서 연구 쿼리를 입력하고 에이전트의 작업 과정을 실시간으로 모니터링할 수 있습니다.
AI-Q 커스터마이징: 워크플로우, 추적 및 모델 설정
configs/config_web_docker.yml 파일을 열어보세요. 이 파일은 LLM, 도구, 에이전트, 워크플로우 구성을 모두 제어하는 핵심 설정 파일입니다.
llms 섹션에서는 사용할 모델들을 선언합니다. 여기서 특히 enable_thinking 플래그에 주목할 만한데, 이는 Nemotron의 생각의 사슬(Chain-of-Thought) 추론 기능을 활성화하거나 비활성화하는 스위치입니다. 다음 예시는 서로 다른 역할을 가진 세 가지 LLM을 정의하고 있습니다.
llms:
nemotron_llm_non_thinking:
_type: nim
model_name: nvidia/nemotron-3-super-120b-a12b
temperature: 0.7
max_tokens: 8192
chat_template_kwargs:
enable_thinking: false
nemotron_llm:
_type: nim
model_name: nvidia/nemotron-3-super-120b-a12b
temperature: 1.0
max_tokens: 100000
chat_template_kwargs:
enable_thinking: true
gpt-5-2:
_type: openai
model_name: 'gpt-5.2'
nemotron_llm_non_thinking은 생각의 사슬로 불필요한 추론으로 지연이 발생하는 상황에서 빠른 응답을 제공합니다. 반면 nemotron_llm은 다단계 추론을 요구하는 에이전트를 위해 100K 컨텍스트 윈도우와 함께 ‘thinking 모드’를 활성화합니다. 여기에 오케스트레이션을 위한 프런티어 모델인 gpt-5.2가 포함됩니다.
이 블루프린트는 섈로 및 딥 리서치 에이전트를 모두 포함하며, 아래 설정에서 두 에이전트의 구성을 확인할 수 있습니다.
functions:
shallow_research_agent:
_type: shallow_research_agent
llm: nemotron_llm
tools:
- web_search_tool
max_llm_turns: 10
max_tool_calls: 5
deep_research_agent:
_type: deep_research_agent
orchestrator_llm: gpt-5
planner_llm: nemotron_llm
researcher_llm: nemotron_llm
max_loops: 2
tools:
- advanced_web_search_tool
섈로 리서치 에이전트는 최대 10회의 LLM 턴과 5회의 도구 호출로 제한된 루프를 실행하며, 인용구가 포함된 간결한 답변을 내놓습니다. “CUDA란 무엇인가?”와 같은 단순한 질문은 단 몇 초 만에 해결됩니다. 반면 딥 리서치 에이전트는 할 일 목록, 파일 시스템, 서브 에이전트를 갖춘 LangChain 딥 에이전트를 활용해 인용 기반의 장문 리포트를 생성합니다.
모든 추론 과정을 온프레미스 환경에서 유지하고 싶다면 orchestrator_llm이 자체 호스팅 모델을 가리키도록 변경하면 됩니다.
실행 추적 모니터링
AI-Q 에이전트를 정밀하게 모니터링하려면 LangSmith 트레이싱 기능을 활성화하세요. 이를 통해 각 쿼리가 생성하는 LangChain 도구 호출 및 모델 사용량 등 전체 실행 경로를 파악할 수 있는 권한이 주어집니다. deploy/.env 파일에 LANGSMITH_API_KEY를 추가하고, 설정 파일에 아래와 같이 텔레메트리 섹션을 삽입하면 됩니다.
general:
telemetry:
tracing:
langsmith:
_type: langsmith
project: aiq-gtc-demo
api_key: ${LANGSMITH_API_KEY}
각 쿼리는 전체 실행 과정을 기록하는 트레이스를 생성합니다.
섈로 리서치 샘플 쿼리:
"지구에서 가장 깊은 곳은 어디인가요?"
딥 리서치 샘플 쿼리:
마리아나 해구의 챌린저 해연을 베료브키나 동굴, 콜라 슈퍼딥 시추공 등 지상 극지와 비교하여, 지구상에서 가장 깊은 지점에 대한 2026년 현재의 과학적 합의를 분석하세요. 최신 해저 지형 및 측지 측정치, 중력 및 압력 센서 보정을 포함한 측정 불확실성 평가, 하달(Hadal) 존의 지형과 생물학적 생태계에 대한 이해를 갱신한 2020~2026년 사이의 최근 심해 탐사 요약을 포함해야 합니다.
트레이스를 확장하면 각 노드를 정밀하게 검사할 수 있습니다. 특히 웹 검색 도구 호출은 디버깅에 매우 유용한데, 에이전트가 전송한 정확한 쿼리와 반환된 결과를 직접 확인하는 것이 가능하기 때문입니다. 개별 트레이스를 넘어 LangSmith를 활용하면 지연 시간, 토큰 사용량, 오류율을 시계열로 추적하고 성능 저하에 대한 알림을 설정할 수도 있습니다.
딥 에이전트 최적화
딥 리서치 에이전트를 특정 도메인에 맞게 조정하려면 우선 서브 에이전트들이 어떻게 조립되는지 살펴보아야 합니다. 이 에이전트는 LangChain의 deepagents 라이브러리에 포함된 create_deep_agent 팩토리를 사용합니다.
from deepagents import create_deep_agent
return create_deep_agent(
model=self.llm_provider.get(LLMRole.ORCHESTRATOR),
system_prompt=orchestrator_prompt,
tools=self.tools,
subagents=self.subagents,
middleware=custom_middleware,
skills=self.skills,
).with_config({"recursion_limit": 1000})
이 팩토리는 오케스트레이터 LLM, 도구, 그리고 두 개의 서브 에이전트를 하나로 엮어줍니다.
self.subagents = [
{
"name": "planner-agent",
"system_prompt": render_prompt_template(
self._prompts["planner"], tools=self.tools_info,
),
"tools": self.tools,
"model": self.llm_provider.get(LLMRole.PLANNER),
},
{
"name": "researcher-agent",
"system_prompt": render_prompt_template(
self._prompts["researcher"], tools=self.tools_info,
),
"tools": self.tools,
"model": self.llm_provider.get(LLMRole.RESEARCHER),
},
]
컨텍스트 관리는 딥 에이전트가 작동하는 방식의 핵심입니다. 플래너 에이전트는 JSON 형태의 리서치 계획을 생성합니다. 리서처 에이전트는 이 계획만 전달받으며, 오케스트레이터의 thinking 토큰이나 플래너의 내부 추론 과정은 전달받지 않습니다. 구조화된 페이로드만 전달함으로써 토큰 낭비를 줄이고, 방대한 컨텍스트 윈도우 속에 묻힌 중요한 지시를 LLM이 놓치는 ‘lost in the middle’ 현상을 방지할 수 있습니다. 이러한 분리는 각 서브 에이전트가 자신의 역할에 집중할 수 있게 합니다. 아래 예시는 검색 증강 생성(RAG)과 롱 컨텍스트 접근 방식을 비교하는 쿼리에 대해 플래너가 생성한 출력입니다:
{
"report_title": "RAG vs Long-Context Models for Enterprise Search",
"report_toc": [
{
"id": "1",
"title": "Architectural Foundations",
"subsections": [
{"id": "1.1", "title": "Retrieval-Augmented Generation Pipeline"},
{"id": "1.2", "title": "Long-Context Transformer Architectures"}
]
},
{
"id": "2",
"title": "Performance and Accuracy Trade-offs",
"subsections": [
{"id": "2.1", "title": "Factual Accuracy and Hallucination Rates"},
{"id": "2.2", "title": "Latency and Throughput Benchmarks"}
]
}
],
"queries": [
{
"id": "q1",
"query": "RAG retrieval-augmented generation architecture components ...",
"target_sections": ["Architectural Foundations"],
"rationale": "Establishes baseline understanding of RAG pipelines"
}
]
}
이 아키텍처는 Deep Research Bench 및 Deep Research Bench II 모두에서 우수한 성능을 내도록 튜닝되었습니다.
특정 도메인에 맞게 에이전트를 커스터마이징하려면 src/aiq_aira/agents/deep_researcher/prompts/에 위치한 프롬프트 템플릿을 수정하세요. 예를 들어, planner.j2를 열어 보고서의 개요를 3개 섹션 이내로 제한하도록 지시하면 더욱 집중도 높은 리포트를 얻을 수 있습니다. 또한 추가적인 디버그 로그를 생성하여 중간 상태(예: /planner_output.md)를 확인하면, 프롬프트 수정이 서브 에이전트 간에 전달되는 컨텍스트에 어떤 영향을 미치는지 직접 점검하는 것도 가능합니다.
데이터 소스 추가
본 블루프린트는 모든 도구를 NeMo Agent Toolkit 함수로 구현합니다. 새로운 기업용 데이터 소스를 연결하려면 NeMo Agent Toolkit 함수를 구현하고 설정 파일에서 이를 참조하면 됩니다.
1단계: NeMo Agent Toolkit 함수 구현
다음 예시는 내부 지식 베이스(KB) API에 연결하는 과정을 보여줍니다.
# sources/internal_kb/src/register.py
from pydantic import Field, SecretStr
from nat.builder.builder import Builder
from nat.builder.function_info import FunctionInfo
from nat.cli.register_workflow import register_function
from nat.data_models.function import FunctionBaseConfig
class InternalKBConfig(FunctionBaseConfig, name="internal_kb"):
"""Search tool for the internal knowledge base."""
api_url: str = Field(description="Knowledge base API endpoint")
api_key: SecretStr = Field(description="Authentication key")
max_results: int = Field(default=5)
@register_function(config_type=InternalKBConfig)
async def internal_kb(config: InternalKBConfig, builder: Builder):
async def search(query: str) -> str:
"""Search the internal knowledge base for relevant documents."""
results = await call_kb_api(config.api_url, query, config.max_results)
return format_results(results)
yield FunctionInfo.from_fn(search, description=search.__doc__)
NeMo Agent Toolkit은 시작 단계에서 설정 필드의 유효성을 검사하므로, 설정 오류가 발생하더라도 즉각적인 확인이 가능합니다. 에이전트는 해당 함수에 작성된 독스트링을 참조하여 도구 호출 시점을 스스로 판단합니다.
2단계: 설정 파일 내 도구 참조
functions 섹션에 새 도구를 선언한 뒤, 각 에이전트의 tools 목록에 이를 추가하세요.
functions:
internal_kb_tool:
_type: internal_kb
api_url: "https://kb.internal.company.com/api/v1"
api_key: ${INTERNAL_KB_API_KEY}
max_results: 10
shallow_research_agent:
_type: shallow_research_agent
llm: nemotron_llm
tools:
- web_search_tool
- internal_kb_tool
deep_research_agent:
_type: deep_research_agent
orchestrator_llm: gpt-5
planner_llm: nemotron_llm
researcher_llm: nemotron_llm
tools:
- advanced_web_search_tool
- internal_kb_tool
에이전트 코드를 직접 수정할 필요는 전혀 없습니다. 에이전트가 새로운 도구의 이름과 설명을 자동으로 인식하며, LLM은 쿼리가 일치할 때 해당 도구를 알아서 호출합니다. 이와 동일한 패턴으로 기업 고유의 시스템을 연결하거나, MCP를 활용해 기존 도구에 대한 접근 권한을 에이전트에게 부여할 수 있습니다. 이를 통해 조직에서 가장 중요한 데이터와 깊이 통합되면서도, 리서치 스택의 프라이버시를 철저히 보호하는 환경이 완성됩니다.
더 알아보기
AI-Q 블루프린트를 확장하면 LangChain 기반 딥 에이전트를 기업 환경에 빠르게 도입할 수 있습니다. 다음 자료를 통해 여정을 이어가세요.
- 데이터 소스 추가를 위한 블루프린트 커스터마이징 가이드
- AI 팩토리 배포를 위한 Helm 차트
- 평가 기반 개발을 위한 블루프린트 평가 가이드
- 운영 환경 모니터링 및 성능 유지 관리용 LangSmith
현재 Aible, Amdocs, Cloudera, Cohesity, Dell, Distyl, H2O.ai, HPE, IBM, JFrog, LangChain, ServiceNow, and VAST 등 생태계 전반의 파트너사들이 NVIDIA AI-Q 블루프린트를 자사 솔루션에 통합하고 있습니다.
