7장 Nexus 에이전트 플랫폼 기초 정리 (Agent Platform 입문)
개요
Nexus는 AI 에이전트 개념을 실습하면서 익히기 위해 설계된 학습용 오픈 소스 에이전트 플랫폼이다. 구조는 최대한 단순하게 유지하면서도, 실제 에이전트 시스템에서 사용하는 핵심 개념(페르소나, 액션/툴, 지식/메모리, 플래닝/피드백 등)을 모두 담도록 설계되어 있다. 그래서 "개념 이해용 실험실"에 가깝지만, 동시에 꽤 실용적인 에이전트 앱을 만들 수 있는 수준의 기능을 제공한다.
Nexus의 기본 인터페이스는 Streamlit 기반의 웹 챗 애플리케이션으로, ChatGPT나 Gemini와 비슷한 대화 경험을 제공한다. 사용자는 모델과 에이전트 설정(페르소나, 사용할 액션, 지식/메모리, 플랜 방식)을 고르고 곧바로 대화를 시작할 수 있으며, 개발자는 동일 플랫폼 위에서 에이전트와 액션 코드를 수정·확장하며 실험할 수 있다.
이 노트에서는 Nexus의 목적과 특징, 인터페이스 구조, 에이전트를 구성하는 요소, 다른 LLM/에이전트 프레임워크 속에서의 위치, 실행/설치 방법, 그리고 학습·개발용 실행 모드(빠른 실행 vs 개발 모드)를 기초 수준에서 정리한다.
Nexus 에이전트 플랫폼의 목적과 특징
Nexus의 가장 큰 목적은 "에이전트를 구성하는 핵심 개념을 이해하고 실습하도록 돕는 것"이다. 상용 서비스 수준의 복잡한 플랫폼이 아니라, 책과 예제를 통해 단계적으로 확장해 나갈 수 있는 교수용/학습용 플랫폼으로 만들어졌다. 그래서 구조가 비교적 단순하고, 코드가 전부 파이썬으로 작성되어 있어 따라가기가 쉽다.
동시에 Nexus는 단순한 데모를 넘어서, 실제 에이전트 시스템의 필수 구성 요소를 폭넓게 포함한다. 에이전트의 페르소나/프로필, 사용할 액션/툴, 추가 지식이나 메모리, 플래닝과 피드백 방식 등을 GUI에서 선택하고 조합할 수 있게 해 주며, 이 설정을 바탕으로 LLM과 상호작용하는 전체 "에이전트 파이프라인"을 체험할 수 있다.
플랫폼 자체는 계속 확장 가능한 구조를 가지고 있다. 책의 각 장을 따라가면서 새로운 기능(예: 더 복잡한 액션, 메모리 구조, 플래닝 전략 등)을 Nexus에 추가하는 방식으로 학습하게 되어 있어, 단순히 "완성된 제품을 사용하는" 것이 아니라 "에이전트 플랫폼을 스스로 구성해 보는" 경험에 초점이 맞춰져 있다.
Nexus 인터페이스 개요: Streamlit 기반 챗 UI
Nexus의 기본 인터페이스는 Streamlit으로 구현된 웹 챗 애플리케이션이다. 사용자는 브라우저에서 접속해 로그인한 뒤, 새로운 채팅 스레드를 만들고 에이전트와 대화를 주고받는다. 화면 구성을 보면 ChatGPT나 Gemini, 여타 상용 LLM 챗앱과 매우 유사한 형태를 취한다.
Streamlit은 파이썬 코드만으로 웹 UI를 빠르게 만드는 프레임워크이다. Nexus는 이 장점을 활용해, 에이전트 선택, 페르소나/프로필 선택, 사용할 모델(API) 선택, 액션/툴 선택, 플래닝/피드백 옵션 선택 등을 모두 Streamlit UI 위에서 제어할 수 있게 했다. 사용자는 마치 상용 LLM 챗앱에서 "설정"을 바꾸는 것처럼, 에이전트의 속성을 실험적으로 바꾸면서 동작 차이를 바로 확인할 수 있다.
내부적으로 Streamlit 앱은 "상태를 가지지 않는(stateless)" 방식으로 동작하지만, 세션 상태(session state)를 통해 대화 메시지 목록이나 선택된 옵션을 유지한다. 사용자가 메시지를 입력할 때마다 전체 스크립트가 다시 실행되지만, 세션 상태에 메시지 로그를 저장해두고 이를 다시 그려주는 식으로 챗 UI가 유지된다. 장기적인 저장은 별도의 데이터베이스 및 Nexus의 채팅 관리 컴포넌트가 담당한다.
에이전트를 구성하는 주요 요소
Nexus에서 하나의 에이전트를 구성할 때는 크게 네 가지 요소를 고려한다. 페르소나/프로필, 액션/툴, 지식/메모리, 그리고 플래닝/피드백 옵션이다. 이 네 요소는 에이전트가 "어떤 성격과 목표를 갖고, 무엇을 할 줄 알며, 무엇을 알고 있고, 어떻게 계획하고 개선하는지"를 정의한다.
1. 페르소나(Persona) / 프로필(Profile)
페르소나는 에이전트의 "성격과 동기"를 정의한다. 예를 들어, "친절한 초보자용 프로그래밍 튜터", "엄격한 코드 리뷰어", "요약에 특화된 비서"와 같은 역할이 페르소나를 통해 표현된다. 프로필은 이 페르소나를 구체화한 설정(설명, 말투, 전문 분야, 목표 등)을 포함하며, 에이전트는 이 프로필을 기반으로 사용자 요청에 답변하는 방식과 톤을 결정한다.
Nexus에서는 여러 페르소나/프로필을 만들고, 그 중 하나를 선택해서 에이전트를 실행할 수 있다. 같은 모델과 같은 액션을 쓰더라도, 페르소나를 바꾸면 전혀 다른 스타일과 전략의 답변을 얻을 수 있으므로, 페르소나 설계는 에이전트 설계의 핵심 요소가 된다.
2. 액션(Actions) / 툴(Tools)
액션/툴은 에이전트가 실제로 "할 수 있는 일"을 정의한다. 여기에는 단순히 텍스트를 생성하는 것 외에, 외부 함수 호출, 코드 실행, API 호출, 데이터베이스 조회, 특정 알고리즘 수행 등이 포함될 수 있다.
Nexus에서는 액션을 두 가지 관점에서 다룬다. 하나는 LLM 프롬프트 기반의 "시맨틱(semantic) 함수"이고, 다른 하나는 파이썬 코드로 구현된 "네이티브(native) 함수"이다. 시맨틱 함수는 LLM에게 특정 형식의 답변을 요구하는 템플릿 프롬프트를 말하고, 네이티브 함수는 실제 코드 실행(예: 검색, 계산, 파일 입출력 등)을 담당한다. 에이전트는 필요할 때 이 액션들을 호출해 더 복잡한 태스크를 수행한다.
Nexus의 장점은 이 액션들을 독립적으로 개발·테스트할 수도 있고, 전체 에이전트 내에서 통합된 형태로 동작시키며 실험할 수도 있다는 점이다. 이는 학습자가 "하나의 툴을 어떻게 설계하고, 에이전트가 그 툴을 언제 어떻게 쓰게 할지"를 단계적으로 이해하는 데 도움이 된다.
3. 지식(Knowledge) / 메모리(Memory)
지식/메모리는 에이전트가 기본 모델 외에 추가로 접근할 수 있는 정보 자원을 의미한다. 예를 들어, 프로젝트 문서, 사용자 과거 대화 기록, 도메인 지식, 요약된 문헌 등이 여기에 포함될 수 있다.
메모리는 보통 여러 층위로 나뉜다. 단기 메모리(현재 대화 맥락), 장기 메모리(과거 대화나 사용자 프로필), 그리고 의미 기반 검색(semantic memory)을 위한 임베딩 데이터베이스 등이 대표적이다. Nexus는 이런 다양한 메모리 개념을 실습할 수 있는 플랫폼으로, 에이전트가 "모델 자체 지식 + 외부 지식/메모리"를 같이 활용해서 답변하는 구조를 이해하도록 돕는다.
4. 플래닝(Planning) / 피드백(Feedback)
플래닝은 에이전트가 복잡한 목표를 여러 단계로 나누고, 각 단계에 어떤 액션을 사용할지 계획하는 과정이다. 예를 들면 "문제 분석 → 필요한 정보 수집 → 후보 답변 생성 → 검토 및 수정"과 같은 작업 흐름을 에이전트가 스스로 세우도록 하는 것이다.
피드백은 이 계획과 실행 결과에 대해 평가하고 수정하는 과정이다. 피드백은 사용자로부터 직접 받을 수도 있고, 별도의 "평가용 에이전트"나 규칙 기반 체크를 통해 자동으로 줄 수도 있다. Nexus에서는 에이전트를 실행할 때 어떤 종류의 플래닝 및 피드백 옵션을 사용할지 선택할 수 있도록 설계되어, 각 옵션이 결과와 에이전트 행동에 어떤 차이를 만드는지 비교 실험하기 좋다.
Nexus의 위치: 다양한 AI 플랫폼/툴킷 속에서의 역할
현재 LLM/에이전트 생태계에는 수많은 프레임워크와 플랫폼이 존재한다. 예를 들어, Semantic Kernel(SK)이나 LangChain은 주로 "도구 모음(toolkit)" 형태로, LLM 호출, 프롬프트 템플릿, 체인, 메모리, 에이전트 구조 등을 코드 레벨에서 조합할 수 있게 해 준다. 반면 AutoGen, CrewAI 같은 프로젝트는 보다 "완성된 에이전트/멀티에이전트 플랫폼"에 가깝다.
Nexus는 이들 사이에서 "학습과 실험에 초점을 둔 오픈 소스 에이전트 플랫폼"이라는 위치를 차지한다. 단순히 라이브러리만 제공하는 것이 아니라, 완성된 챗 UI, 사용자·채팅 관리, 에이전트 설정 UI를 포함하는 전체 애플리케이션을 제공하면서, 동시에 내부 구현을 직접 수정하고 확장할 수 있게 해 둔 것이 특징이다.
그 결과, Nexus는 다음과 같은 용도로 특히 적합하다.
에이전트 개념(페르소나, 툴, 메모리, 플랜)을 처음 배우는 학습용 실습 환경
SK, LangChain 등으로 만든 개별 액션/툴을 하나의 플랫폼 안에 통합해 보는 실험
상용 수준의 대형 프레임워크에 들어가기 전에, 전체 에이전트 시스템 구조를 "작게 축소한 모델"로 이해하는 단계
Nexus 실행 방법: 설치, OpenAI API 키 설정, 앱 실행
Nexus는 기본적으로 Python 3.10 환경에서 동작하도록 설계되어 있다. 처음 사용할 때는 "빠른 실행 모드"로 패키지를 바로 설치해서 실행할 수 있고, 개발을 위해서는 저장소를 클론한 뒤 "개발 모드"로 설치해 사용할 수 있다.
1. 기본 설치 및 빠른 실행 절차
새 파이썬 가상환경(3.10)을 만든다.
터미널에서 Nexus를 원격 저장소에서 직접 설치한다.
pip install git+https://github.com/cxbxmxcx/Nexus.gitOpenAI API 키를 환경 변수나
.env파일로 설정한다. 예시는 다음과 같다.bash 예시
export OPENAI_API_KEY="<your API key>"PowerShell 예시
$env:OPENAI_API_KEY = "<your API key>"혹은
.env파일에 저장echo 'OPENAI_API_KEY="<your API key>"' > .env
다음 명령으로 앱을 실행한다.
nexus run브라우저가 자동으로 열리며 로그인/회원가입 페이지가 나타난다. 새 사용자를 생성하고 로그인하면, 기본 챗 화면이 뜨고 새로운 채팅을 만들어 에이전트와 대화를 시작할 수 있다.
OpenAI API 키 설정이 잘못되어 있으면 모델 호출 단계에서 오류가 발생하므로, 문제가 생길 경우 가장 먼저 키 설정을 확인하는 것이 좋다.
Nexus 개발 모드 실행: 소스 코드 기반 학습·개발
책의 예제나 자신만의 기능을 추가하며 학습하려면, Nexus를 "개발 모드"로 사용하는 것이 좋다. 이 모드에서는 저장소를 직접 클론하고, 로컬 코드 수정이 바로 적용되는 형태로 Nexus를 설치한다.
1. 개발 모드 설치 절차
새로운 작업 디렉터리를 만들고, 그 안에 파이썬 가상환경(3.10)을 만든다.
Nexus 저장소를 클론한다.
git clone https://github.com/cxbxmxcx/Nexus.git클론한 프로젝트를 "editable" 모드로 설치한다.
pip install -e Nexus이 방식은 로컬 폴더의 코드를 수정하면, 재설치 없이 바로 Nexus 실행에 반영되도록 해 준다.
OpenAI API 키를 환경 변수 또는
.env파일로 설정한다(빠른 실행 때와 동일).다음 명령으로 애플리케이션을 실행한다.
nexus run
브라우저에 나타나는 로그인/회원가입 화면에서 새 사용자를 생성하면, 이후에는 쿠키를 통해 사용자 정보가 저장되므로 브라우저에서 다시 접속할 때 자동 로그인되는 형태로 동작한다(브라우저에서 쿠키를 비활성화하지 않았다면).
Nexus의 내부 구조와 학습 관점에서의 의미
Nexus 저장소를 열어보면, 상단에는 Streamlit로 구현된 인터페이스 레이어가 있고, 그 아래에는 채팅 시스템, 데이터베이스, 에이전트 매니저, 액션 매니저, 프로필 매니저 등이 계층적으로 배치된 구조를 확인할 수 있다. 인터페이스는 사용자의 입력·선택을 받아 채팅 시스템에 전달하고, 채팅 시스템은 적절한 에이전트와 액션, 메모리를 조합해 LLM과 통신한 뒤 결과를 다시 UI에 반환한다.
이 아키텍처는 "하나의 에이전트 플랫폼이 어떤 구성 요소로 이루어지는지"를 직관적으로 보여준다. 학습자는 UI, 에이전트/프로필 관리, 액션 관리, 메모리 및 데이터베이스의 역할을 분리해서 이해할 수 있으며, 각 레이어에서 어떤 코드를 수정하면 어떤 행동 변화가 생기는지를 실험을 통해 체감할 수 있다.
예를 들어, Streamlit 코드 일부를 수정해 챗 UI를 바꿔볼 수도 있고, 프로필 정의 파일을 수정해 에이전트의 페르소나를 바꿔볼 수도 있으며, 액션 모듈에 새로운 시맨틱 함수나 네이티브 함수를 추가해 에이전트가 할 수 있는 일을 늘려볼 수도 있다. 이런 식으로 Nexus는 "에이전트 이론"을 "코드와 UI로 구현된 살아 있는 예제"로 연결해 주는 플랫폼이다.
정리 및 활용 방향
Nexus 에이전트 플랫폼은 에이전트 개념을 처음부터 끝까지 한 번에 체험해 보기 위한, 단순하지만 강력한 학습용 오픈 소스 플랫폼이다. Streamlit 기반의 챗 UI 덕분에 사용자는 상용 LLM 챗앱과 매우 비슷한 경험으로 에이전트를 사용하면서도, 내부 코드를 직접 열어보고 페르소나, 액션, 메모리, 플랜 전략 등을 바꿔가며 실험할 수 있다.
실전적으로 활용하려면 다음과 같은 순서를 추천할 수 있다.
빠른 실행 모드로 설치 후, 기본 에이전트로 대화를 해 보며 전반적인 사용 감각 익히기
제공된 페르소나/프로필을 바꿔 보며 답변 스타일 차이 관찰하기
간단한 시맨틱 액션부터 만들어 Nexus에 추가해 보고, 에이전트가 이 툴을 어떻게 사용하는지 확인하기
개발 모드로 전환해, 메모리/지식 구조나 플래닝 옵션을 수정·확장해 보는 실습 진행하기
이 과정을 통해 Nexus는 단순한 "채팅 앱"을 넘어, 에이전트 아키텍처와 설계 패턴을 실제 코드와 UI를 통해 이해할 수 있는 실습 환경으로 활용될 수 있다.