JYP Garden

LangChain Agents

Properties1
tagssource, agentic-architecture, knowledge

8 min read

LangChain Agents

Source: langchain-agents Type: 공식 문서 (Documentation) By: LangChain Team Valid as of: 2026-04-27

핵심 Takeaway

  • Agent = Reasoning Engine + Tool Executor + Memory Loop: LLM이 의사결정 중추이고 도구는 외부 실행, 메시지 상태가 기억을 관리하는 폐쇄 루프 구조
  • ReAct 패턴 구현: 에이전트는 reasoning 단계와 action(tool call) 단계를 반복; 단일 모델 호출로 다중 도구 호출 지원
  • 정적 vs 동적 구성: 모델·도구·시스템프롬프트를 정적(고정)으로 설정하거나 런타임 조건(복잡도, 역할)에 따라 동적으로 선택 가능
  • Middleware 확장성: 상태 전처리, 응답 수정, 도구 오류 처리, 동적 모델 선택, 로깅을 hooks로 자유롭게 삽입 가능
  • LangChain SDK의 수렴점: create_agent() 함수와 AgentState 스키마로 프로덕션 에이전트의 boilerplate를 표준화

상세 요약

1. Agent 아키텍처

LangChain Agent는 message-driven loop 구조다. 사용자 입력이 message 상태에 추가되면, 모델이 다음 action을 결정한다.

루프 사이클:

  1. 사용자 메시지 입력 → Agent 상태에 추가
  2. 모델이 상태를 읽고 다음 도구 호출 또는 최종 답변 결정
  3. 도구 실행 → observation을 상태에 추가
  4. 모델이 새로운 상태를 읽고 재판단
  5. 반복 (최대 iteration 수 또는 모델이 종료 신호 전송)

이 메커니즘은 ReAct (Reasoning + Acting) 패턴을 자연스럽게 구현한다. 각 사이클에서 모델은 “왜 이 도구를 쓰는가”를 판단하고, 그 결과를 통합해 다음 도구를 선택한다.

2. 핵심 컴포넌트: Model

모델은 reasoning engine이다. LangChain은 두 가지 설정 패턴을 지원한다.

정적 모델 선택

모델을 agent 생성 시점에 고정:

  • 문자열로 지정: "openai:gpt-5.4"
  • 직접 인스턴스: ChatAnthropic(model="claude-opus", temperature=0.5)

파라미터 (temperature, max_tokens, timeout 등)를 세밀하게 제어할 수 있다.

동적 모델 선택

런타임 조건에 따라 모델을 변경:

  • @wrap_model_call 데코레이터로 미들웨어 작성
  • 조건: 대화 복잡도, 메시지 누적 수, 사용자 권한 등
  • 효과: 단순 질문은 저가 모델, 복잡 추론은 고가 모델로 자동 라우팅

3. 핵심 컴포넌트: Tools

핵심 원칙: “정확성이 중요하면 LLM이 계산하면 안 된다”

도구는 Python 함수 또는 coroutine이다. LangChain은 @tool 데코레이터로 함수를 자동으로 등록하고, 모델이 도구를 호출할 수 있게 스키마를 생성한다.

정적 도구

agent 생성 시 미리 정의:

tools = [calculator, wikipedia_search, database_query]
agent = create_agent(model, tools)

동적 도구

런타임에 도구를 추가/필터링:

  • 사용자 권한에 따라 일부 도구 비활성화
  • MCP (Model Context Protocol) 서버에서 외부 도구 자동 발견
  • 이전 도구 호출 결과에 따라 새로운 도구 등록

도구 호출 전략

  • 순차 호출: 첫 도구 결과 후 다음 도구 호출 (기본)
  • 병렬 호출: 여러 도구를 동시 실행 (I/O 작업 효율화)
  • 조건부 호출: 이전 결과에 따라 도구 선택
  • 재시도 로직: 도구 오류 시 자동 재실행

4. 핵심 컴포넌트: System Prompt

시스템 프롬프트는 에이전트 행동 가이드다. LangChain은 다음을 지원한다.

정적 프롬프트

문자열로 고정:

system_prompt = "You are a helpful assistant. Always use tools when needed."
agent = create_agent(model, tools, system_prompt=system_prompt)

또는 Anthropic 특화 SystemMessage로 prompt caching 활성화 가능.

동적 프롬프트

@dynamic_prompt 데코레이터로 런타임 프롬프트 생성:

  • 사용자 역할에 따른 지시사항 추가 (admin vs user)
  • 현재 컨텍스트에 따른 행동 조정

5. 고급 기능

Structured Output (응답 포맷 지정)

에이전트가 반환할 결과를 JSON 스키마로 정의:

  • ToolStrategy: 모든 모델에서 작동 (도구 호출 활용)
  • ProviderStrategy: 특정 모델 네이티브 지원 (OpenAI structured outputs, Anthropic beta)

Memory (대화 이력 관리)

에이전트는 자동으로 message 상태에서 대화 이력을 유지한다.

커스텀 메모리를 추가하려면 AgentState 스키마 확장:

class CustomState(AgentState):
    user_preferences: dict
    previous_goals: list[str]
    sentiment: str  # 사용자 감정 추적

Streaming (점진적 결과 표시)

agent.stream(state, stream_mode="values")로 중간 단계 표시:

  • 사용자가 에이전트의 사고 과정을 실시간 관찰
  • 다중 도구 호출 시 각 호출의 진행상황 노출

Middleware (확장 훅)

LangChain 에이전트는 다양한 지점에 미들웨어를 삽입할 수 있다:

  • 모델 호출 전: 상태 전처리, 토큰 수 제한, 조건부 라우팅
  • 모델 호출 후: 응답 검증, 환각 감지, 토큰 사용량 로깅
  • 도구 오류 처리: 도구 실패 시 재시도, fallback 도구 실행
  • 동적 모델 선택: 복잡도 기반 라우팅
  • 카스텀 로깅: 감사 추적(audit trail) 기록

6. Agent 호출

에이전트를 실행하는 최소 코드:

agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ]
})

이 호출은 메시지를 agent 상태에 추가하고, ReAct 루프를 시작한다. 모델은 필요시 도구를 호출하고, 최종 답변을 생성한다.

연결되는 위키 페이지

  • agentic-ai-patterns — 에이전트 설계의 4가지 패턴(Reflection, Tool Use, Routing, Hierarchical)과 LangChain 구현의 대응 관계
  • langchain-agents-architecture — 신규 페이지: LangChain 에이전트의 구체적 아키텍처와 프로덕션 패턴
  • langchain — 신규 페이지: LangChain 프레임워크 개요, SDK 구성, 생태계

그래프 뷰