LangChain Agent로 복잡한 워크플로우 자동화를 구현하려는 분들이 요즘 정말 많아요. 저도 홈랩(Home Lab, 개인 실험 환경)에서 여러 자동화 파이프라인을 굴리다가, 단순한 스크립트 몇 개로는 더 이상 감당이 안 되는 시점이 왔거든요. 알림은 Slack으로 보내고, 장애 징후는 로그에서 뽑고, 사용자 요청은 요약하고, 필요한 경우엔 외부 API까지 호출해야 했습니다. 처음엔 Python으로 if 문 덕지덕지 붙이면 되겠지 했었는데, 금방 한계가 왔어요. 그때 정리해서 도입한 방식이 바로 LangChain Agent 기반 워크플로우 자동화였습니다.

이 글에서는 Agent SDK 활용 관점에서, 실제로 LangChain의 에이전트 구성 요소와 Tool(에이전트가 호출하는 기능 단위)을 조합해 어떻게 복잡한 흐름을 관리했는지 풀어보겠습니다. 거창한 데모보다, 제가 직접 해보면서 부딪힌 포인트를 중심으로 썼어요. 혹시 자동화가 점점 커지면서 스크립트가 엉키기 시작했다면 꽤 공감되실 겁니다.

왜 LangChain Agent가 워크플로우 자동화에 잘 맞을까

쉽게 말해 LangChain Agent는 LLM 에이전트(대형 언어 모델 기반 작업 판단기)가 상황을 읽고, 필요한 Tool을 골라서 순서대로 실행하게 만드는 구조입니다. 예전엔 제가 직접 분기 로직을 다 짰어요. 예를 들면 “에러 로그가 있으면 요약하고, 장애 패턴이면 티켓 만들고, 아니면 보고서만 저장” 같은 흐름이었죠. 이걸 전부 코드로 박아두면 처음엔 단순한데, 조건이 늘어날수록 유지보수가 지옥이 됩니다.

근데 LangChain Agent를 붙이면 판단 레이어를 어느 정도 유연하게 분리할 수 있어요. 물론 모든 걸 LLM에게 맡기면 안 됩니다. 여기서 중요한 포인트! 결정은 에이전트가 하되, 실행은 검증된 Tool이 하도록 분리해야 합니다. 저는 이 구조를 쓰고 나서 자동화가 훨씬 읽기 쉬워졌고, 장애 원인 추적도 편해졌더라고요.

LangChain Agent가 요청을 받아 분석하고, 여러 Tool과 검증 단계를 거쳐 결과를 반환하는 전체 흐름을 보여주는 이미지입니다.

LangChain 사례로 보는 기본 구조

제가 실제로 많이 쓴 패턴은 아래 4단계였습니다.

1. 입력 수집: 사용자 요청, 로그, 이벤트, 티켓 내용을 받습니다.
2. 의도 분류: 요약인지, 분석인지, 외부 시스템 호출이 필요한지 구분합니다.
3. Tool 실행: 검색, 저장, 알림, 티켓 생성 같은 실제 작업을 수행합니다.
4. 결과 검증: 응답 포맷과 필수 필드가 맞는지 확인합니다.

이 구조가 좋은 이유는 명확해요. LLM은 텍스트 해석과 판단에 강하고, 실제 시스템 변경은 함수나 API가 담당하니까요. 다시 말해 자유도는 높이고, 위험도는 낮추는 방식입니다. 저도 처음엔 “에이전트가 너무 똑똑한 척하다가 이상한 Tool 고르면 어쩌지?” 싶었는데, Tool 설계를 보수적으로 하면 꽤 안정적으로 돌아가더라고요.

실전 구현 1: 워크플로우 자동화 시나리오 정의

제가 예제로 자주 설명하는 시나리오는 이렇습니다. 운영 중인 서비스에서 장애 의심 이벤트가 들어오면, 에이전트가 로그를 요약하고, 중요도를 분류하고, 필요한 경우 운영 채널에 알림을 보내고, 마지막으로 리포트를 저장하는 거예요. 말로 하면 쉬운데, 이걸 사람이 수동으로 하려면 은근 반복 작업이 많거든요.

저는 먼저 Tool 목록부터 아주 보수적으로 잘랐습니다. 이게 진짜 중요합니다.

• search_logs: 최근 로그 검색
• classify_severity: 중요도 분류
• notify_slack: Slack 알림 전송
• save_report: 결과 저장

처음엔 Tool을 이것저것 많이 붙였는데 오히려 에이전트가 헷갈리더라고요. 실제로 써보니까 Tool 수를 줄이고, 각 Tool 책임을 명확히 나누는 것이 훨씬 낫습니다.

환경 준비

python -m venv .venv
source .venv/bin/activate
pip install langchain langchain-openai

여기서는 가장 단순한 형태로만 가져갑니다. 패키지 버전은 시점에 따라 바뀌기 때문에, 프로젝트에서는 lock file로 고정하는 걸 추천드립니다. 저도 처음엔 로컬에선 되는데 서버에선 안 되는 문제를 몇 번 겪었습니다 ㅎㅎ

기본 Tool 정의

from typing import Literal
from langchain.tools import tool

@tool
def search_logs(query: str) -> str:
    """Search recent logs by keyword and return a short summary."""
    sample = [
        "api-gateway timeout after 30s",
        "db connection pool exhausted",
        "retry succeeded for payment worker"
    ]
    matched = [line for line in sample if query.lower() in line.lower()]
    return "\n".join(matched) if matched else "no relevant logs"

@tool
def classify_severity(log_summary: str) -> Literal["low", "medium", "high"]:
    """Classify operational severity from log summary."""
    text = log_summary.lower()
    if "pool exhausted" in text or "timeout" in text:
        return "high"
    if "retry" in text:
        return "medium"
    return "low"

@tool
def notify_slack(message: str) -> str:
    """Send a message to an operations channel."""
    return f"sent to slack: {message}"

@tool
def save_report(content: str) -> str:
    """Save an incident report."""
    return "report saved"

실무에서는 당연히 실제 로그 시스템이나 메시징 API를 붙이겠죠. 다만 구조는 크게 다르지 않습니다. LLM은 실행 주체가 아니라 오케스트레이터(Orchestrator, 작업 조율자)라고 생각하시면 이해가 쉽습니다.

에이전트가 어떤 기준으로 Tool을 고르고, 각 Tool이 어떤 입력과 출력을 갖는지 보여주는 구성 이미지입니다.

실전 구현 2: LangChain Agent 연결

이제 Tool을 에이전트에 연결해보겠습니다. 제가 처음 이 부분에서 좀 헤맸던 이유가, 프롬프트에 역할과 제약을 충분히 안 적어서였습니다. 에이전트는 생각보다 지시를 문자 그대로 받아들이거든요.

from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [search_logs, classify_severity, notify_slack, save_report]

prompt = ChatPromptTemplate.from_messages([
    ("system", """
You are an operations automation agent.
Use tools to investigate incidents.
If severity is high, notify slack.
Always save a final report.
Do not invent log data.
Return a concise final summary.
"""),
    ("human", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

agent = create_openai_functions_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

result = executor.invoke({
    "input": "Investigate database timeout symptoms and create an incident summary."
})

print(result["output"])

여기서 핵심은 세 가지예요.

1. Do not invent log data처럼 금지 조건을 명시합니다.
2. Always save a final report처럼 필수 행동을 적습니다.
3. 최종 응답은 사람이 읽기 쉬운 형태로 짧게 제한합니다.

이렇게 해두면 LLM 에이전트가 지나치게 산으로 가는 걸 많이 줄일 수 있어요. 저도 처음엔 프롬프트를 너무 추상적으로 써서 Tool 호출 순서가 들쭉날쭉했는데, 운영 기준을 문장으로 박아두니까 꽤 안정됐습니다.

실전 구현 3: 다단계 워크플로우 자동화로 확장하기

한 단계 더 나가면 조건부 분기와 검증 로직을 붙일 수 있습니다. 예를 들어 중요도가 high일 때만 Slack 알림을 보내고, 결과는 반드시 JSON으로 저장하도록 강제하는 식이죠. 저는 운영 자동화에서 이 검증 단계를 빼먹었다가 나중에 리포트 형식이 제각각이라 한참 정리했던 적이 있습니다. 삽질 좀 했습니다 ㅎㅎ

import json
from pydantic import BaseModel, ValidationError

class Report(BaseModel):
    summary: str
    severity: str
    action_taken: str


def validate_report(payload: str) -> str:
    data = json.loads(payload)
    report = Report(**data)
    return report.model_dump_json(ensure_ascii=False)

final_payload = json.dumps({
    "summary": "Database timeout patterns detected from recent logs.",
    "severity": "high",
    "action_taken": "Slack notification sent and report saved."
}, ensure_ascii=False)

print(validate_report(final_payload))

이건 에이전트 바깥에서 검증하는 예시입니다. 제 경험상 에이전트 결과를 바로 믿지 말고, 마지막엔 애플리케이션 레벨에서 검증하는 게 안전합니다. 특히 워크플로우 자동화가 외부 시스템을 건드릴수록 더 그렇습니다.

⚠️ 트러블슈팅: 제가 실제로 겪었던 문제들

여기부터가 진짜 실전입니다. 데모는 잘 돌아가는데 운영에 붙이면 꼭 이상한 부분이 생기거든요.

1. Tool 설명이 모호하면 엉뚱한 함수가 호출됩니다

예전에 notify와 save 관련 Tool 설명을 둘 다 “store result” 비슷하게 써둔 적이 있었는데, 에이전트가 자꾸 저장만 하고 알림은 안 보내더라고요. 그 뒤로는 Tool docstring을 아주 구체적으로 씁니다.

• notify_slack: 운영 채널에 즉시 알림을 보냄
• save_report: 최종 리포트를 파일 또는 저장소에 기록

설명이 겹치면 안 됩니다. 정말 사소해 보이는데 체감 차이가 커요.

2. 프롬프트만으로 제어하려고 하면 흔들립니다

처음엔 “high면 알림 보내”를 프롬프트에만 적어뒀습니다. 그런데 상황에 따라 누락되는 경우가 있더라고요. 이후에는 애플리케이션 쪽에도 한 번 더 조건문을 넣었습니다. 즉, 프롬프트 제약 + 코드 제약 이중으로 묶는 방식입니다.

3. 로그 요약이 길어지면 판단 품질이 떨어집니다

이건 꽤 자주 겪습니다. 입력 컨텍스트가 너무 길면 핵심 장애 패턴이 묻혀버리거든요. 그래서 저는 최근 로그를 전부 넣지 않고, 사전 필터링을 거친 뒤 요약본만 넣습니다. 쉽게 말해 검색(Search)과 추출(Extraction)을 먼저 하고, 에이전트 판단은 그 다음입니다.

4. 실패 경로를 안 만들면 운영에서 곤란합니다

API 호출 실패, 응답 지연, 빈 결과 같은 케이스를 빼먹기 쉽습니다. 근데 실제 운영은 정상보다 예외가 더 기억에 남습니다. 그래서 아래처럼 실패 응답도 표준화해두는 걸 추천드립니다.

workflow:
  on_error:
    notify: true
    save_fallback_report: true
    retry_policy:
      enabled: true
      max_attempts: 3

이거 해두면 밤에 훨씬 편합니다. 진짜로요.

Tool 실패, 재시도, 대체 보고서 저장 같은 예외 처리 경로를 시각적으로 설명하는 이미지입니다.

검증과 결과: 자동화가 실제로 편해졌는지 확인하는 방법

자동화는 “돌아간다”보다 “믿고 맡길 수 있다”가 중요합니다. 저는 보통 아래 항목으로 검증합니다.

1. 같은 입력에 대해 비슷한 결과가 나오는가
2. high severity에서 알림 누락이 없는가
3. 결과 저장 포맷이 항상 일정한가
4. 실패 시 fallback 경로가 작동하는가

간단한 테스트 스크립트도 붙여봅니다.

test_inputs = [
    "database timeout",
    "retry succeeded",
    "unknown warning"
]

for item in test_inputs:
    output = executor.invoke({"input": f"Investigate: {item}"})
    print(item)
    print(output["output"])
    print("-" * 40)

이 단계에서 중요한 건 벤치마크 숫자를 화려하게 만드는 게 아닙니다. 오히려 재현성(reproducibility, 같은 조건에서 비슷한 결과가 나오는 성질)과 예측 가능성이 더 중요합니다. 제가 직접 해보니, 사람 손을 완전히 없애는 자동화보다 “1차 분석과 정리까지 맡기는 자동화”가 훨씬 현실적이고 만족도도 높았습니다.

자동화 실행 결과, 중요도 분류, 알림 여부, 리포트 저장 상태를 한눈에 보여주는 대시보드 이미지입니다.

LangChain Agent 도입 전 체크리스트

무조건 Agent부터 붙이기보다, 아래를 먼저 확인하시면 시행착오를 많이 줄일 수 있습니다.

• Tool이 충분히 분리돼 있는가
• 실패했을 때 사람이 이어받을 수 있는가
• 출력 검증 로직이 있는가
• LLM에게 맡길 판단과 코드로 고정할 규칙이 구분돼 있는가
• 로그와 실행 기록을 남기고 있는가

특히 마지막은 꼭 챙기세요. 나중에 “왜 이런 판단을 했지?”를 보려면 실행 흔적이 있어야 합니다. 이전 글에서 다뤘던 운영 로그 정리 방식이 있다면 그 구조를 그대로 재활용해도 좋습니다. 다음 글에서는 이런 흐름을 더 확장해서 멀티스텝 승인(approval) 자동화까지 다뤄볼 예정입니다.

자주 묻는 질문

Q1. LangChain Agent는 모든 자동화에 필요한가요?

아닙니다. 분기가 거의 없고 입력과 출력이 고정돼 있다면 일반 스크립트가 더 단순하고 좋습니다. 에이전트는 판단이 필요한 자동화에서 빛이 납니다.

Q2. LLM 에이전트가 실수하면 위험하지 않나요?

맞습니다. 그래서 실제 시스템 변경은 제한된 Tool만 허용하고, 검증 단계를 별도로 둬야 합니다. 저는 읽기와 분류는 넓게, 쓰기와 변경은 좁게 가져갑니다.

Q3. Agent SDK 활용 포인트를 한 줄로 정리하면요?

판단은 유연하게, 실행은 보수적으로입니다. 이 원칙 하나만 지켜도 워크플로우 자동화 품질이 꽤 달라집니다.

도입 전후 차이, Tool 설계 원칙, 검증 전략을 요약한 마무리 인포그래픽 이미지입니다.

마무리: 복잡한 워크플로우 자동화, 결국 설계가 반입니다

LangChain Agent를 써보면 처음엔 되게 마법처럼 느껴져요. 자연어로 시키면 알아서 Tool을 고르니까요. 근데 실제로 오래 굴려보면, 잘 되는 이유는 모델이 똑똑해서라기보다 Tool 경계, 프롬프트 제약, 검증 로직을 얼마나 잘 설계했느냐에 달려 있더라고요. 저도 처음엔 이게 뭔가 싶었는데, 구조를 한 번 제대로 잡고 나니 워크플로우 자동화가 한결 차분해졌습니다.

정리하면 이렇습니다. LangChain Agent는 복잡한 워크플로우 자동화에 꽤 강력한 도구예요. 하지만 무턱대고 붙이기보다, 에이전트가 판단할 영역과 코드가 통제할 영역을 분리해야 진짜 실무형으로 살아남습니다. 혹시 지금 자동화 스크립트가 점점 괴물이 되어가고 있다면, 작은 Tool 몇 개부터 분리해서 LLM 에이전트로 묶어보세요. 생각보다 빨리 “아, 이래서 쓰는구나” 하는 순간이 옵니다. 드디어 됐다! 싶은 지점이 분명히 생기거든요.