아프니까 개발자다 아프니까 개발자다

RAG 파이프라인을 에이전트에 붙이려는 순간 벽을 만난다. 리트리버는 list[Document]를 돌려주는데, 에이전트 도구는 문자열을 기대한다. 이 둘을 연결하는 접착제가 build_context이고, @tool 데코레이터는 그 함수를 에이전트가 직접 선택하고 호출할 수 있는 도구로 탈바꿈시킨다. 이 글은 그 연결 고리가 어떻게 작동하는지, 그리고 도구를 하나로 합치지 않고 카테고리별로 분리하는 이유가 무엇인지를 살펴본다.1. 리트리버와 에이전트 사이의 다리 — build_context리트리버는 질문과 유사한 청크를 벡터 DB에서 꺼내 문서 목록으로 반환한다. 그런데 에이전트 도구의 반환 타입은 문자열이어야 한다. 에이전트는 도구가 돌려준 문자열을 자신의 프롬프트에 이어 붙여 최종 답변을 생성하기 때문..

1. 배경 — LLM이 모르는 것들LLM은 학습 시점에 공개된 데이터만 알고 있다. 인터넷에 공개된 텍스트, 코드, 논문이 재료다. 반면 영화 정보 자료, 사내 위키, 어제 올라온 뉴스, 그리고 내가 작성한 문서는 학습에 포함되지 않는다. "올해 개봉한 '그 영화'의 OST를 누가 작곡했어?"를 물으면 LLM은 그냥 모른다.이 문제를 해결하는 방법으로 파인튜닝(fine-tuning)이 먼저 떠오른다. 우리 문서를 데이터셋으로 만들어 LLM에 추가 학습시키는 것이다. 하지만 파인튜닝은 비용이 크고, 문서가 업데이트될 때마다 재학습이 필요하다는 결정적인 문제가 있다. 영화 정보 한 줄이 바뀔 때마다 모델을 다시 굽는 건 현실적이지 않다.RAG(Retrieval-Augmented Generation)는 다른 ..

LangGraph 그래프를 완성했다. 이제 실행해야 한다. 실행 방법은 두 가지다: graph.invoke와 graph.stream. 단순히 "빠른 것"과 "느린 것"의 차이가 아니다. 두 방식은 에이전트의 내부 동작을 어떻게 관찰하느냐의 차이다—그리고 이것이 디버깅에서 결정적인 역할을 한다.invoke: 결과만 받는 동기 실행graph.invoke는 그래프 전체를 실행하고 최종 상태를 반환한다. 에이전트가 중간에 도구를 세 번 호출하든 한 번도 안 하든, 호출자 입장에서는 모른다. 완료됐을 때 최종 messages 리스트만 돌아온다.from langchain_core.messages import HumanMessage# 입력: messages 리스트로 감싸서 전달result = graph.invoke(..

LangGraph의 상태(State)가 무엇이고 어떻게 설계하는지 알았다면, 이제 그 상태를 가지고 에이전트 워크플로우를 실제로 조립하는 법을 볼 차례다. LangGraph에서 그 조립 도구가 StateGraph다. StateGraph는 설계도다. 노드를 등록하고, 엣지로 연결하고, 컴파일하면 실행 가능한 에이전트가 된다. 이 글은 StateGraph를 구성하는 API 하나하나 — add_node, add_edge, add_conditional_edges, compile — 가 각각 무슨 일을 하고, 어떤 선택을 내리는지를 분해한다.1. StateGraph — 에이전트 설계도를 만드는 빌더LangGraph에서 에이전트 워크플로우를 만드는 방식은 빌더 패턴(builder pattern)이다. StateGr..

LangChain이 해결한 문제는 명확했다. LLM을 쓸 수 있는 형태로 만들기 위한 반복 작업을 없애는 것이다. 그런데 에이전트를 실제로 만들다 보면 또 다른 벽에 부딪힌다."결과가 부족하면 다시 검색한다." 이 한 문장을 코드로 표현하는 순간, 선형 체인(Chain)은 한계를 드러낸다. 루프가 없기 때문이다. 체인은 A → B → C로 흘러갈 수는 있어도, "C가 충분하지 않으면 B로 돌아가라"는 구조를 표현할 방법이 없다.LangGraph는 그 한계를 해결하기 위해 2024년에 등장했다. LangChain의 연장선이지만, 패러다임이 다르다. 선형(linear)에서 그래프(graph)로 달라졌다.1. 배경 — LangChain의 체인(Chain)이 충분하지 않았던 이유LangChain의 초기 핵심 개..

LLM마다 코드를 따로 써야 했던 시절OpenAI GPT를 쓰다가 Anthropic Claude로 바꾸려면 얼마나 손봐야 할까? 2023년 초까지만 해도 대답이 단순했다. "코드를 거의 다시 써야 한다." 각 LLM 제공사(provider)가 저마다 다른 SDK, 다른 함수 이름, 다른 요청 형식을 썼기 때문이다.LLM provider별로 완전히 다른 코드가 필요한 상황. 위 다이어그램은 동일한 "AI에게 질문하기"라는 목적을 달성하기 위해 provider마다 함수 이름, 매개변수 이름, 메시지 포맷이 모두 다른 현실을 보여 준다. OpenAI는 client.chat.completions.create(), Anthropic은 client.messages.create(), Google은 generate_c..

2022년 말 ChatGPT가 공개된 이후, 개발자들 사이에서 한 가지 공통된 질문이 등장했다."LLM을 내 서비스에 어떻게 집어넣지?"답은 간단해 보였다. API를 호출하면 된다. 그런데 실제로 해보면 달랐다. 대화 이력을 직접 관리해야 하고, 외부 검색 기능을 붙이려면 연결 코드를 따로 짜야 하고, LLM이 여러 번 판단을 반복하도록 루프를 구현해야 했다. 강력한 언어 모델을 손에 쥐었는데, 정작 그것을 "쓸 수 있는 형태"로 만드는 데 시간의 대부분을 써야 했다.LangChain은 그 반복을 없애려는 시도로 2022년 10월에 등장했다.1. 배경 — GPT 등장 이후 개발자들이 맞닥뜨린 문제LLM(Large Language Model, 거대 언어 모델) API는 사실 단순하다. 텍스트를 보내면 텍스..

Claude Code에서 서브에이전트를 만드는 방법은 두 가지다. 하나는 텍스트 에디터로 마크다운 파일을 직접 작성하는 방법이고, 다른 하나는 /agents 명령어로 대화형 UI를 열어 만드는 방법이다. 파일을 직접 작성하는 방식이 더 세밀한 제어가 가능하지만, 처음 만들어 보거나 빠르게 프로토타입을 만들 때는 /agents UI가 훨씬 빠르다.서브에이전트란 무엇인가 — 팀장이 팀원에게 위임하는 구조서브에이전트는 메인 Claude가 특정 작업을 위임하는 전문화된 AI 조수다. 팀장(메인 Claude)이 "보안 감사는 보안팀한테 맡겨"라고 결정하면, 보안팀(서브에이전트)이 독립된 컨텍스트에서 작업하고 결과 요약만 돌려보낸다.메인 Claude가 두 서브에이전트에게 작업을 동시에 위임한다. 독립 컨텍스트에서 ..