복습 음성 · 25분 4초 · AI Agent와 LangGraph의 원리와 실습 · 20장 · 파일에 1.1배속 적용

AI Agent(인공지능 에이전트)는 모델의 판단과 도구의 실행을 연결해 사용자의 목표를 수행한다. 요청을 읽고 필요한 행동을 고른 뒤 결과를 확인해 다음 작업을 정한다. LangGraph는 이 과정에서 상태와 작업 경로를 관리한다.

복습 음성에서는 기술 용어와 코드명을 영어 발음으로 읽는다. 파일에 1.1배속을 적용했으므로 플레이어는 1.0배속으로 두면 된다.

모델은 판단하고 도구는 실행한다

모델은 입력된 문맥을 읽고 답변이나 행동 요청을 만든다. 도구는 검색, 계산, 문서 읽기와 저장처럼 정해진 기능을 수행한다. 모델이 사용할 도구와 입력값을 제안하면 프로그램이 도구를 실행하고 결과를 돌려준다.

Orchestration(오케스트레이션)은 작업 순서와 분기, 반복, 종료를 관리한다. 다음 판단에 필요한 정보를 보관하고 실행 결과에 맞춰 경로를 정한다. 에이전트 코드를 읽을 때도 모델 호출, 도구 호출, 그래프의 역할을 구분해 본다.

앞 단계의 결과를 다음 판단에 반영하면서 여러 단계의 작업이 연결된다. 모델이 선택할 행동의 범위와 사용할 도구, 종료 조건은 개발자가 정한다. 시스템의 자율성도 이 범위 안에서 이루어진다.

State에 담을 정보

State(상태)는 여러 작업이 공유할 정보다. 각 작업이 읽을 입력과 다음 작업에 전달할 결과에 따라 상태의 항목을 정한다. 데이터 분석 그래프에는 대화 메시지, 실행할 코드, 코드 실행 결과를 담는다.

Node(노드)는 현재 상태를 받아 작업을 수행하고 변경값을 반환하는 함수다. 코드 선택 노드는 실행할 코드를 만들고 코드 실행 노드는 계산 결과를 만든다. 답변 노드는 계산 결과를 읽어 사용자에게 설명한다.

Reducer(상태 갱신 규칙)는 기존 값과 새 값을 합치는 방식이다. 코드와 실행 결과는 최신 값으로 갱신한다. 메시지에 쓰는 add_messages는 새 메시지를 추가하고 같은 식별자의 메시지는 갱신한다. LangGraph Graph API 문서

Edge(연결)는 다음 노드를 정한다. 일반 연결은 지정한 노드로 이동하고 조건부 연결은 판단 함수의 선택값에 따라 경로가 달라진다. 모델의 판단을 Structured output(구조화 출력)으로 받으면 선택값을 정해진 항목에 담아 경로와 연결할 수 있다.

도구 호출이 실행되는 과정

도구에는 이름과 설명, 입력 형식이 있다. 모델은 이 정보를 읽고 사용할 도구와 입력값을 정한다. bind_tools는 도구의 사용 형식을 모델에 전달한다. LangChain Tools 문서

모델이 만든 도구 호출 요청을 프로그램이 받아 실행한다. 데이터 분석에서는 제안된 Python 코드를 실행 도구에 전달하고 여러 도구를 쓰는 그래프에서는 ToolNode가 요청에 해당하는 도구를 실행한다. 모델 메시지에는 호출 요청이, 도구 메시지에는 실행 결과가 담긴다.

실습에서는 도구를 개별적으로 확인한 뒤 그래프에 연결한다. 데이터프레임의 열과 자료형을 확인하고 실제 계산 대상을 도구에 연결한다. PDF 작성에서는 한글 글꼴과 다음 줄의 작성 위치를 정한다. 저장한 문서를 다시 읽어 입력과 파일 결과를 대조한다.

대화 기억과 원래 질문

Checkpoint(상태 저장본)는 실행 과정의 상태를 보관한 기록이다. InMemorySaver는 현재 실행 환경의 메모리에 기록을 보관한다. 같은 thread_id로 질문하면 해당 대화의 상태를 이어서 활용하고 새 식별자로 질문하면 새 대화 흐름을 시작한다. LangGraph Persistence 문서

반복 그래프에서는 원래 질문을 상태의 별도 항목에 둔다. 도구 실행 뒤에는 도구 결과가, 응답 생성 뒤에는 모델 응답이 메시지의 마지막에 들어간다. 원래 질문을 따로 유지하면 진행 중에도 목표를 계속 참조할 수 있다.

전체 기록을 보관하는 범위와 모델에게 전달할 문맥의 범위는 따로 정한다. 단기 기억 함수는 최근 메시지를 골라 모델 입력의 범위를 관리한다. 저장된 기록과 실제 모델 입력을 대조해 어떤 메시지를 기억으로 활용하는지 확인한다.

답변 평가와 종료 조건

반복 그래프는 도구 선택, 도구 실행, 응답 정리 뒤에 답변 평가를 둔다. 평가가 종료 경로를 선택하면 실행을 마친다. 추가 작업 경로를 선택하면 도구 선택으로 돌아가 앞에서 얻은 결과를 다음 행동에 반영한다.

종료 조건에는 목표 달성과 실행 범위를 함께 넣는다. 같은 도구와 입력의 반복, 시도 횟수, 도구 선택 상태를 기록해 종료 여부를 정한다. recursion_limit은 한 차례 실행에 허용할 슈퍼 스텝 수를 정하며 실행 제한에 도달하면 GraphRecursionError가 발생한다. LangGraph 실행 제한 문서

평가 결과는 실제 산출물과 대조한다. 보고서 작업이라면 저장한 파일과 읽기 결과를 확인한다. 모델의 완료 판단과 작업의 실제 완료 상태를 기록해두면 종료 근거를 따라갈 수 있다.

실습에서 확인할 것

실습 그래프는 데이터 분석과 대화 기억을 연결한다. 여러 도구를 쓰는 그래프에는 답변 평가와 반복 경로도 붙인다. 실행 환경과 데이터를 준비하고 상태의 항목, 작업별 함수, 분기와 종료 경로를 연결한다. 질문을 넣은 뒤에는 도구 결과와 최종 답변을 대조하고 실행 기록을 남긴다.

수행할 작업 확인할 결과 습득할 내용
데이터와 도구 연결 열과 자료형, 실제 계산 대상 모델 입력과 실행 데이터의 관계
상태 정의와 갱신 확인 값의 생성 위치와 활용 위치 상태 설계와 메시지 갱신
분석과 기억 경로 비교 계산 결과, 답변, 노드 방문 기록 조건부 분기와 대화 기억
데이터 전환 데이터와 도구와 대화 설정 같은 그래프의 데이터 전환
검색과 PDF 도구 확인 검색 결과, 저장 파일, 읽기 결과 도구의 입력과 산출물
반복 그래프 구성 평가 후 재진입과 종료 경로 결과를 다음 행동에 반영하는 원리
실행 제한 실습 진행 기록과 실행 제한 오류 반복의 실행 범위 관리
검색 도구만 사용하는 실습 답변, 파일 상태, 종료 이유 목표와 도구 지원 범위의 관계
파일 변경 도구의 권한 검토 실행 대상과 범위 및 확인 절차 도구 목록과 행동 권한

파일 삭제를 다루는 선택 항목은 대상과 권한, 사람의 확인 절차를 읽어보는 범위로 둔다. 실제 파일에 영향을 주는 행동인 만큼 도구의 기능과 실행 권한을 같이 살펴본다.

실행 기록에는 질문과 설정, 도구 이름과 입력, 실행 결과, 노드 방문, 걸린 시간, 종료 이유를 남긴다. 노드 방문 수, 모델 호출 수, 토큰 사용량과 비용은 구분해서 읽는다. 모델 호출은 노드 내부와 분기 판단 함수에서 이루어질 수 있다.

복습할 때는 실행 기록을 펴놓고 그래프의 동작을 내 말로 설명해본다. 어떤 정보를 유지했고 어떤 도구를 선택했으며 어떤 결과를 얻어 어떤 이유로 종료했는지 연결할 수 있으면 학습한 내용을 확인하기 쉽다.

개인 학습 자료를 바탕으로 쓴 개념 정리다. 모델과 도구의 실제 실행 결과는 각 실습의 기록과 산출물로 확인한다. API 동작의 근거는 각 절의 공식 문서에 연결했다.