1. NVIDIA NeMo Agent Toolkit 설치 및 시작해보았습니다

 

 

GitHub - NVIDIA/NeMo-Agent-Toolkit: The NVIDIA NeMo Agent toolkit is an open-source library for efficiently connecting and optim

 

사실 깃허브 보다는 공식 문서를 보자. 본 내용은 아래의 doc 번역에 가깝다

 

NVIDIA NeMo Agent Toolkit Overview — NVIDIA NeMo Agent Toolkit (1.5)

 

 

나의 사용환경은 Ubuntu 24.04 LTS Desktop

1. 폴더 및 가상환경 생성

sudo mkdir nemo # 폴더명은 원하는대로
python3 -m venv nemo
cd nemo
source bin/activate # 가상환경 활성화

# 필수로 다운받아야 하는 의존성
sudo apt-get install git
sudo apt-get install git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
# curl이 설치되어 있지 않으면 sudo apt-get install curl

uv pip install nvidia-nat
# 충돌의 문제가 있기 때문에 most로 밑의 명령어들을 한번에 설치한다
uv pip install "nvidia-nat[most]


# nvidia-nat[most]에 다 포함되어 있다
pip install "nvidia-nat[langchain]"
pip install "nvidia-nat-adk" # Google ADK 
pip install "nvidia-nat-eval" # Nemo 평가 기능
pip install "nvidia-nat-mcp" # MCP
pip install "nvidia-nat-mysql" # MySQL
pip install "nvidia-nat-test" # Nemo 테스트

 

만약에 개발하기 전에 Nemo Agent Toolkit에 대해서 만져보고 싶다면 Installation의 Install from Source를 따라한다.

# 1. Nemo Agent Toolkit 레포지토리를 clone
git clone -b main https://github.com/NVIDIA/NeMo-Agent-Toolkit.git nemo-agent-toolkit
cd nemo-agent-toolkit

# Git에서 서브모듈을 업데이트
git submodule update --init --recursive

# 데이터셋 다운로드
git lfs install
git lfs fetch
git lfs pull

# 가상환경 생성 파이썬 버전은 3.11 이상이면 상관없다
uv venv --python 3.13 --seed .venv
source .venv/bin/activate

# Nemo Agent Toolkit의 기능을 한번에 설치하는 --all-groups, 
# 플러그인과 성능 분석을 위한 --extra most를 설
uv sync --all-groups --extra most
uv sync

uv pip install -e ".[langchain]"
uv pip install -e ".[eval,profiling]"

# 제대로 설치되었는지 확인
nat --help
nat --version

 

Get started > Tutorials > Customize a Workflow

 

Workflow는 사용할 툴과 모델을 정의하는 YAML configuration 파일이다. 

예시로 examples/getting_started/simple_web_query/configs/config.yaml 을 살펴보자. 해당 파일들은 위의 Install from Sources에서 git clone해온 것이다. 

functions:
  webpage_query:
    _type: webpage_query
    webpage_url: https://docs.smith.langchain.com
    description: "Search for information about LangSmith. For any questions about LangSmith, you must use this tool!"
    embedder_name: nv-embedqa-e5-v5
    chunk_size: 512
  current_datetime:
    _type: current_datetime

llms:
  nim_llm:
    _type: nim
    model_name: meta/llama-3.1-70b-instruct
    temperature: 0.0

embedders:
  nv-embedqa-e5-v5:
    _type: nim
    model_name: nvidia/nv-embedqa-e5-v5

workflow:
  _type: react_agent
  tool_names: [webpage_query, current_datetime]
  llm_name: nim_llm
  verbose: true
  parse_agent_response_max_retries: 3

다음과 같은 워크플로우는 langchaing에 대해서 질문하는 webpage_query와 현재 시간을 반환하는 current_datetime 두개의 툴을 가진다. 그리고 임베딩 모델과 LLM 모델을 포함한다. 두 개를 따로 쓰는 이유는 서로 잘하는 분야가 다르기 때문. 임베딩 모델은 관련 있는 내용을 찾기 위해서 먼저 사용하고 이를 다시 대답하기 위해서 LLM을 쓴다. LLM이 사용자의 질문을 보고 어떤 툴을 쓸지 결정한다. 

nat run --config_file examples/getting_started/simple_web_query/configs/config.yml --input "What is LangSmith?"  \
  --override llms.nim_llm.temperature 0.7

위와 같은 경우 react_agent가 "Langchain에 대해서' 묻는 사용자의 질문을 파악하고 webpage_query 툴을 사용해야한다고 판단하고 해당 툴을 호출한다. Workflow의 매개변수는 --override flag를 사용하여 오버라이드할 수 있다. 

 

Get started > Tutorials > Add Tools to a Workflow

 

앞에서는 매개변수를 조절하는 법을 보앗다면 이번에는 새로운 툴을 추가해보자. 새로운 툴을 추가하기 위해서는 Workflow configuration file을 조작해야한다. 앞에서 다음과 같은 Workflow를 보았다.

functions:
  webpage_query:
    _type: webpage_query
    webpage_url: https://docs.smith.langchain.com
    description: "Search for information about LangSmith. For any questions about LangSmith, you must use this tool!"
    embedder_name: nv-embedqa-e5-v5
    chunk_size: 512

근데 만약에 Workflow가 모르는 것에 대해서 질문을 받는다면? LangSmith에 대해서만 알던 tool에 LangChain에 대해서 질문해보았다. 

nat run --config_file examples/getting_started/simple_web_query/configs/config.yml --input "How do I trace only specific parts of my LangChain application?"
# 라는 질문에 대해서 
Workflow Result:
["Unfortunately, the provided webpages do not provide specific instructions on how to trace only specific parts of a LangChain application using LangSmith. However, they do provide information on how to set up LangSmith tracing with LangChain and how to use LangSmith's observability features to analyze traces and configure metrics, dashboards, and alerts. It is recommended to refer to the how-to guide for setting up LangSmith with LangChain or LangGraph for more information."]
# 라고 대답한다

Workflow를 Langgraph Quickstart guide에 대해서도 알 수 있도록 업데이트해줘야 한다. 먼저 원래의 workflow configuration filed을 복사한 다음 업데이트한다.

functions:
  langsmith_query:
    _type: webpage_query
    webpage_url: https://docs.smith.langchain.com
    description: "Search for information about LangSmith. For any questions about LangSmith, you must use this tool!"
    embedder_name: nv-embedqa-e5-v5
    chunk_size: 512
  langchain_query:
    _type: webpage_query
    webpage_url: https://docs.smith.langchain.com/observability/how_to_guides/trace_with_langchain
    description: "Search for information about LangChain. For any questions about LangChain, you must use this tool!"
    embedder_name: nv-embedqa-e5-v5
    chunk_size: 512

툴을 수정하였으니 workflow를 다음과 같이 업데이트한다.

workflow:
  _type: react_agent
  tool_names: [langsmith_query, langchain_query, current_datetime]

각각의 웹페이지에 대해서 workflow를 추가하는건 매우 번거로우니 여러개의 웹페이지를 탐색하는 tavily_internet_search 툴을 사용해보자. 해당 툴은 nvidia-mat-langchain에 포함되어 있다. 해당 기능을 사용하기 위해서는 tavily.com 에 가입하여 API 키를 얻어야 한다. 

functions:
  internet_search:
    _type: tavily_internet_search
  current_datetime:
    _type: current_datetime
workflow:
  _type: react_agent
  tool_names: [internet_search, current_datetime]

이렇게 적용한 다음에 

nat run --config_file examples/documentation_guides/workflows/custom_workflow/search_config.yml \
  --input "How do I trace only specific parts of my LangChain application?"
# 라고 질문하면 알아서 해당 정보가 있는 웹페이지를 찾는다
Workflow Result:
['To trace only specific parts of a LangChain application, users can use the `@traceable` decorator to mark specific functions or methods as traceable. Additionally, users can configure the tracing functionality to log traces to a specific project, add metadata and tags to traces, and customize the run name and ID. Users can also use the `LangChainTracer` class to trace specific invocations or parts of their application. Furthermore, users can use the `tracing_v2_enabled` context manager to trace a specific block of code.']
# 라고 대답

 

Get started > Tutorials > Create a New tool and workflow with NVIDIA NeMo Agent Toolkit

 

위에서는 Agent Toolkit에 포함되어 있던 툴을 사용하는 방법에 대해서 알아보았다. 이번에는 로컬 파일을 가지고 새로운 툴을 만들어본다. nat workflow create 명령어를 사용하여 새로운 워크플로우를 위한 파일 구조와 의존성 파일을 설치한다.

nat workflow create --workflow-dir examples text_file_ingest

해당 명령어는 examples/text_file_ingest 라는 새로운 디렉토리를 생성하고 필수 파일과 폴더를 생성하고 workflow에 필요한 파이썬 패키지를 설치한다. 삭제하려면 nat workflow delete text_file_ingest 를 사용한다. 이런 식으로 만들어진 모든 workflow는 파이썬 프로젝트를 포함한다. 

examples/text_file_ingest
├── configs -> src/text_file_ingest/configs # 관련된 workflow configuration file
├── data -> src/text_file_ingest/data # 예제 데이터 저장
├── pyproject.toml # 패키지 메타데이터 및 의존성 정보
└── src
    ├── text_file_ingest # 파이썬 패키지와 workflow configuration file과 데이터를 저
    │   ├── configs
    │   │   └── config.yml
    │   ├── data
    │   ├── __init__.py
    │   ├── register.py # 일반적으로 툴 구현은 여기서 정의된다
    │   └── text_file_ingest.py # 툴 함수와 생성 객체 정의 뒤에서 알아보자
    └── text_file_ingest.egg-info
        ├── dependency_links.txt
        ├── entry_points.txt
        ├── PKG-INFO
        ├── requires.txt
        ├── SOURCES.txt
        └── top_level.txt

일반적으로, 그리고 이 예제에서는 툴 구현은 register.py 파일에서 정의됩니다. register.py를 다음과 같이 클래스를 구성하자

class TextFileIngestFunctionConfig(FunctionBaseConfig, name="text_file_ingest"):
    ingest_glob: str
    description: str
    chunk_size: int = 1024
    embedder_name: EmbedderRef = "nvidia/nv-embedqa-e5-v5"

아래는 text_file_ingestion_function.py입니다. 툴 함수와 configuration 객체를 정의합니다.

 

@register_function(config_type=TextFileIngestFunctionConfig, framework_wrappers=[LLMFrameworkEnum.LANGCHAIN])
# framework_wrappers를 사용하여 LangChain/LangGraph와의 호환성을 확인
async def text_file_ingest_function(config: TextFileIngestFunctionConfig, builder: Builder):

    from langchain_classic.tools.retriever import create_retriever_tool
    from langchain_community.document_loaders import DirectoryLoader
    from langchain_community.document_loaders import TextLoader
    from langchain_community.vectorstores import USearch
    from langchain_core.embeddings import Embeddings
    from langchain_text_splitters import RecursiveCharacterTextSplitter

    embeddings: Embeddings = await builder.get_embedder(config.embedder_name, wrapper_type=LLMFrameworkEnum.LANGCHAIN)

    logger.info("Ingesting documents from: %s", config.ingest_glob) # 단순한 로깅
    
    # 새로운 툴을 위해서 langchain에서 사용하는 directoryLoader와 TextLoader 클래스
    (ingest_dir, ingest_glob) = os.path.split(config.ingest_glob)
    loader = DirectoryLoader(ingest_dir, glob=ingest_glob, loader_cls=TextLoader)

    docs = [document async for document in loader.alazy_load()]

	# 이건 langchain에서 사용하는 방식 그대
    text_splitter = RecursiveCharacterTextSplitter(chunk_size=config.chunk_size)
    documents = text_splitter.split_documents(docs)
    vector = await USearch.afrom_documents(documents, embeddings)

    retriever = vector.as_retriever()

	# 툴의 새로운 이름을 업데이트 하기 위해 name 변수를 text_file_ingest로 변경
    retriever_tool = create_retriever_tool(
        retriever,
        "text_file_ingest",
        config.description,
    )

    async def _inner(query: str) -> str:

        return await retriever_tool.arun(query)

    yield FunctionInfo.from_fn(_inner, description=config.description)

설명이 좀 불친절한데

 

이제 workflow configuration을 생성하기 위해서 custom_config.yml을 만들어보자. 해당 예시에서 데이터는 workflows/text_file_ingest/data 디렉토리의 DOCA GPUNetIO에 사용된 텍스트 파일들을 사용한다.

 제일 처음에 설명한것과 크게 다르지 않으므로 넘어간다.

functions:
  doca_documents:
    _type: text_file_ingest
    ingest_glob: examples/documentation_guides/workflows/text_file_ingest/data/*.txt
    description: "Search for information about DOCA and GPUNetIO. For any questions about DOCA and GPUNetIO, you must use this tool!"
    embedder_name: nv-embedqa-e5-v5
    chunk_size: 512
  current_datetime:
    _type: current_datetime

llms:
  nim_llm:
    _type: nim
    model_name: meta/llama-3.1-70b-instruct
    temperature: 0.0

embedders:
  nv-embedqa-e5-v5:
    _type: nim
    model_name: nvidia/nv-embedqa-e5-v5

workflow:
  _type: react_agent
  tool_names: [doca_documents, current_datetime]
  llm_name: nim_llm
  verbose: true
  parse_agent_response_max_retries: 3

 

pyproject.toml 파일은 패키지 메타데이터와 의존성을 정의한다. 이번 경우에는 기본적으로 생성된 pyproject.toml으로도 충분하지만 NeMO Agent Toolkit에 포함되지 않은 추가적인 의존성이 존재한다면 업데이트 해줘야할 필요가 잇다. 

 

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=64", "setuptools-scm>=8", "setuptools_dynamic_dependencies>=1.0.0"]

[tool.setuptools_scm]
git_describe_command = "git describe --long --first-parent"

[project]
name = "nvidia-nat"
dynamic = ["version", "dependencies", "optional-dependencies"]
requires-python = ">=3.11,<3.14"
description = "NVIDIA NeMo Agent Toolkit"
readme = "README.md"
license = { text = "Apache-2.0" }
keywords = ["ai", "rag", "agents"]
classifiers = [
  "Programming Language :: Python",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
]
authors = [{ name = "NVIDIA Corporation" }]
maintainers = [{ name = "NVIDIA Corporation" }]

[project.urls]
documentation = "https://docs.nvidia.com/nemo/agent-toolkit/latest/"
source = "https://github.com/NVIDIA/NeMo-Agent-Toolkit"

a2a = ["nvidia-nat-a2a == {version}"]
adk = ["nvidia-nat-adk == {version}"]
agno = ["nvidia-nat-agno == {version}"]
app = ["nvidia-nat-app == {version}"]
...

[dependency-groups]
# Dependency groups are only for developers to aid in managing dependencies local to a dev machine.
dev = [
  "beautifulsoup4~=4.13",
  "httpx-sse~=0.4",
  "ipython~=8.31",
  "langchain-community~=0.3", # web ingest script
  ...

 

패키지 종속성에 사용될 버전은 Git tags에 기반하여 setuptools-csm을 사용하여 자동으로 결정할 수 있다. 위에서 dynamic = ["version"] 이라고 쓰고 setuptools, setuptools_scm에 빌드 의존성을 정의해놓는다. 

 

setuptools_scm에서는 git repository의 루트를 찾을 수 있도록 한다.

[tool.setuptools_scm]
root = "../../../.."

 

새로 workflow를 업데이트 하고 생성했을 때에는 workflow 패키지를 재설치하여 모든 의존성을 확인할 수 있어야 한다.

nat workflow reinstall text_file_ingest

완성되었는지 확인하기 위해서

uv pip install -e examples/documentation_guides/workflows/text_file_ingest
# 테스트 질문 수행
nat run --config_file examples/documentation_guides/workflows/text_file_ingest/configs/config.yml \
   --input "What does DOCA GPUNetIO do to remove the CPU from the critical path?"
# 예시 답변 
Workflow Result:
['DOCA GPUNetIO removes the CPU from the critical path by providing features such as GPUDirect Async Kernel-Initiated Network (GDAKIN) communications, which allows a CUDA kernel to invoke GPUNetIO device functions to receive or send data directly, without CPU intervention. Additionally, GPUDirect RDMA enables receiving packets directly into a contiguous GPU memory area. These features enable GPU-centric solutions that bypass the CPU in the critical path.']

 

Get started > Tutorials > Build a Demo Agent Workflow Using Cursor Rules

 

Cursor rule을 설정해두면 AI는 프레임워크에 특화되어 코딩을 도와줄 수 있습니다. NeMo Agent Toolkit 개발을 돕기 위해서 자연어로 명령하여 환경 셋업이라던가 사용가능한 툴을 찾는것, workflow 생성, 함수 생성등을 할 수 있는 에이전트이다.

 

무조건 설치. 이제 Get Started를 완료하였다