LangChain Deep Agents 가이드: 기능, 도구, 설정

LangChain Deep Agents로 더 강력한 AI 에이전트를 구축하세요. 계획 수립, 도구 호출, 파일 시스템 관리, 서브에이전트 워크플로가 어떻게 자율적인 작업 수행을 가능하게 하는지 알아보고, Kimi API를 연결해 고급 언어 이해와 추론 능력으로 에이전트를 강화해 보세요.

Kimi API 키 받기

12분 읽기2026-08-14

AI 에이전트는 질문에 답하는 것을 넘어 작업을 처음부터 끝까지 처리하기 시작하면서 점점 더 유용해지고 있습니다. LangChain Deep Agents는 에이전트가 작업을 세분화하고, 다양한 도구를 사용하고, 정보를 관리하고, 더 작은 작업들을 조율할 수 있도록 도와 더 많은 제어력과 유연성을 제공합니다. 이를 통해 지속적인 지침 없이도 실제 워크플로를 처리할 수 있는 에이전트를 더 쉽게 만들 수 있습니다. LangChain Deep Agents가 어떻게 작동하는지, 그리고 이를 활용해 무엇을 만들 수 있는지 살펴보겠습니다.

LangChain Deep Agents란 무엇인가요?

LangChain Deep Agents는 LangChain의 핵심 구성 요소와 LangGraph 런타임을 기반으로 구축된 에이전트 프레임워크입니다. 파일 시스템 접근, 서브에이전트 위임, 계획 수립, 메모리, 휴먼 인 더 루프 지원 같은 내장 기능으로 표준 에이전트 워크플로를 확장합니다. Deep Agents는 추론, 도구 호출, 반복적 실행을 결합한 에이전트 루프를 사용하므로, 여러 단계와 대량의 컨텍스트, 조율된 워크플로가 필요한 복잡한 작업에 적합합니다.

단순한 루프로 도구를 호출하는 데 그치는 기본 에이전트와 달리, Deep Agents는 장기 실행 작업을 처리하기 위한 추가 인프라를 제공합니다. 파일을 관리하고, 전문 서브에이전트에 작업을 위임하고, 복잡한 워크플로 전반에서 컨텍스트를 유지하며, 필요할 때 사람의 개입을 허용할 수 있습니다. 이러한 내장 기능은 고급 에이전트 시스템을 구축할 때 필요한 별도의 엔지니어링 작업량을 줄여줍니다.

LangChain Deep Agents의 작동 방식

Deep Agent가 작업을 받으면 요청을 분석하고 작업을 완료하기 위해 필요한 단계를 계획합니다. 그런 다음 검색, 코드 실행, 파일 시스템 작업 등 사용 가능한 도구를 이용해 정보를 수집하고 작업을 수행합니다.

실행 과정에서 Deep Agents는 파일을 읽고 쓰면서 컨텍스트를 관리합니다. 모든 중간 결과를 대화 기록 안에 계속 유지하는 대신, 대량의 정보를 외부에 저장하고 필요할 때 불러올 수 있습니다. 이 방식은 에이전트가 더 긴 워크플로를 처리하면서도 컨텍스트 윈도우 크기로 인한 제약을 줄이는 데 도움이 됩니다.

여러 작업 영역이 관련된 복잡한 작업의 경우, Deep Agents는 특정 하위 작업을 전문 서브에이전트에 위임할 수 있습니다. 각 서브에이전트는 정해진 목표에 집중하며 관련 결과를 메인 에이전트에 반환합니다. 그러면 메인 에이전트는 서브에이전트의 결과물, 검색된 정보, 저장된 파일을 결합해 완전하고 일관된 응답을 생성합니다.

계획 수립, 도구 사용, 파일 시스템 관리, 서브에이전트 협업, 사람의 감독 같은 기능을 통해 LangChain Deep Agents는 다단계의 실제 작업을 처리할 수 있는 더 강력한 AI 시스템을 구축하기 위한 기반을 제공합니다.

Deep Agents의 핵심 기능: 계획 수립, 도구, 실행

Deep Agents는 여러 단계, 결정, 행동이 필요한 작업을 처리할 수 있습니다. 핵심 기능들은 작업을 계획하고, 적절한 도구를 사용하고, 수작업 입력을 줄이면서 각 단계를 효율적으로 완료하도록 돕습니다. 이러한 기능들을 자세히 살펴보겠습니다:

작업 계획 수립

작업 계획 수립을 통해 에이전트는 실행 중에 구조화된 작업 목록을 만들고 관리할 수 있습니다. 복잡한 목표를 하나의 지시로 처리하는 대신, 에이전트는 이를 더 작은 단계로 나누고, 진행 상황을 추적하며, 워크플로 전반에서 작업 상태를 업데이트할 수 있습니다.

계획 수립을 사용해야 할 때

길거나 복잡한 다단계 작업
명확한 진행 상황 추적과 구조화된 실행이 유용한 작업
에이전트 상태로부터 진행 상황을 스트리밍하는 UI

활성화 방법

middleware 매개변수에 TodoListMiddleware를 전달하세요. 이를 통해 에이전트는 상태 추적(pending, in_progress, completed)이 가능한 구조화된 작업 목록을 관리하는 write_todos 도구를 갖게 됩니다.

from deepagents import create_deep_agent
from deepagents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="your-model",
    middleware=[TodoListMiddleware()],
)

작업은 에이전트 상태에 저장되어, 에이전트가 장기 실행 작업을 정리할 수 있는 경량 계획 계층을 제공합니다.

가상 파일시스템 도구

Deep Agents는 인메모리 상태, 로컬 디스크, LangGraph 스토어, 복합 라우팅 또는 권한 규칙이 있는 커스텀 백엔드 등 교체 가능한 백엔드를 기반으로 하는 설정 가능한 가상 파일시스템을 제공합니다.

기본 제공 파일시스템 도구

도구	설명
`ls`	디렉터리 내 파일을 메타데이터(크기, 수정 시간)와 함께 나열
`read_file`	줄 번호와 함께 파일 내용을 읽으며, 대용량 파일을 위한 offset/limit을 지원하고, 이미지, 비디오, 오디오, 문서에 대한 멀티모달 콘텐츠 블록도 반환
`write_file`	새 파일을 생성하거나 기존 파일을 덮어쓰기
`edit_file`	파일 내에서 정확한 문자열 치환 수행(전체 치환 모드 포함)
`delete`	파일 또는 디렉터리를 재귀적으로 삭제
`glob`	패턴과 일치하는 파일 찾기(예: `*/.py`)
`grep`	여러 출력 모드로 파일 내용 검색
`execute`	환경에서 셸 명령 실행(샌드박스 백엔드에서만 가능)

지원되는 멀티모달 확장자

이미지: .png, .jpg, .jpeg, .gif, .webp, .heic, .heif
비디오: .mp4, .mpeg, .mov, .avi, .flv, .mpg, .webm, .wmv, .3gpp
오디오: .wav, .mp3, .aiff, .aac, .ogg, .flac
문서: .pdf, .ppt, .pptx

파일시스템 권한

이 하네스는 에이전트가 읽거나 쓸 수 있는 파일 및 디렉터리를 제어하는 선언적 권한 규칙을 지원합니다. 규칙은 위에서 아래로 평가되며, 처음 일치하는 규칙이 우선 적용됩니다.

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:your-model",
    permissions=[
        {"operations": ["read", "write"], "paths": ["/workspace/**"], "mode": "allow"},
        {"operations": ["read"], "paths": [".env", "**/secrets/**"], "mode": "deny"},
    ],
)

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:your-model",
    permissions=[
        {"operations": ["read", "write"], "paths": ["/workspace/**"], "mode": "allow"},
        {"operations": ["read"], "paths": [".env", "**/secrets/**"], "mode": "deny"},
    ],
)

이를 통해 에이전트를 특정 디렉터리로 제한하고, 민감한 파일을 보호하며, 서브 에이전트에 상위 에이전트보다 더 제한된 접근 권한을 부여할 수 있습니다.

도구 접근 제한하기

FilesystemMiddleware에 tools 허용 목록을 전달하여 파일 시스템 도구 중 일부만 노출할 수 있습니다. read_file은 항상 포함되어야 합니다.

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent
agent = create_deep_agent(
    model="your-model",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent
agent = create_deep_agent(
    model="your-model",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

서브 에이전트(위임)

이 하네스에는 메인 에이전트가 격리된, 장시간 실행되는, 다단계 또는 병렬 작업을 위해 임시 서브 에이전트를 생성할 수 있도록 하는 내장 task 도구가 포함되어 있습니다.

주요 특징

새로운 컨텍스트: 호출마다 자체 컨텍스트를 가진 새로운 에이전트 인스턴스가 생성됩니다.
자율 실행: 서브 에이전트는 완료될 때까지 독립적으로 실행됩니다.
단일 전달: 메인 에이전트에 최종 보고서 하나를 반환합니다.
구성 가능한 전략: 기본 general-purpose 서브 에이전트를 사용하거나 커스텀 서브 에이전트를 정의할 수 있습니다.
컨텍스트 효율성: 무거운 하위 작업은 격리된 상태로 유지되며 간결한 결과로 압축됩니다.

서브 에이전트 비활성화

task 도구 없이 에이전트를 실행하려면, 하네스 프로필을 통해 자동 추가되는 서브 에이전트를 비활성화하고 subagents=를 통해 동기 서브 에이전트를 전달하지 않으면 됩니다. excluded_middleware를 통해 SubAgentMiddleware를 제거하려고 하지 마세요—이는 의도적으로 거부됩니다.

도구 호출 기능

Deep Agents는 세 가지 범주의 도구를 지원합니다:

커스텀 함수 및 LangChain 도구

tools= 매개변수를 통해 커스텀 함수나 LangChain 도구를 직접 전달하세요:

from deepagents import create_deep_agent def get_weather(city: str) -> str: """Get weather for a given city.""" return f"It's always sunny in {city}!" agent = create_deep_agent( model="your-model", tools=[get_weather], system_prompt="You are a helpful assistant", )

MCP(Model Context Protocol)

Deep Agents는 MCP를 완전히 지원하여, 표준 인터페이스를 통해 데이터베이스, API, 파일 시스템 등에 연결할 수 있습니다.

코드 실행

샌드박스 백엔드: 격리된 환경에서 셸 명령을 실행하는 execute 도구를 노출합니다.
인터프리터: 경량 프로그래밍 계층을 위해 범위가 제한된 QuickJS 런타임에서 JavaScript를 실행하는 eval 도구를 추가합니다.

이러한 기능들이 결합되면서, 에이전트를 구동하는 언어 모델은 전체 구성의 중요한 부분이 됩니다. 성능이 좋은 모델은 Deep Agents가 지시를 이해하고, 작업을 추론하며, 사용 가능한 도구를 더 잘 활용하도록 도울 수 있습니다. Kimi API는 이러한 모델 계층을 제공할 수 있어, 더 강력한 Deep Agent 워크플로를 구축하는 자연스러운 다음 단계가 됩니다.

6단계로 Kimi API를 LangChain Deep Agents에 연결하기

성능이 좋은 모델은 Deep Agent가 작업을 효과적으로 처리하는 데 필요한 언어 이해력과 추론 능력을 제공합니다. Kimi API는 에이전트가 도구를 다루고, 작업을 관리하고, 복잡한 지시를 처리하는 동안 이러한 기능을 제공할 수 있습니다. 모델 계층이 갖춰지면, 자연스럽게 Kimi API를 LangChain Agents에 연결하는 단계로 넘어갈 수 있습니다. Kimi API를 LangChain Deep Agents에 연결하는 방법은 다음과 같습니다:

1단계: Kimi API 키 받기

Kimi API 플랫폼에 로그인하여 새 API 키를 생성하세요. Deep Agents 설정에 추가해야 하므로 키를 복사하여 안전하게 보관하세요. 이 API 키는 요청을 인증하여 LangChain의 Deep Agents가 API를 통해 Kimi 모델에 접근할 수 있도록 합니다.

Kimi API 키 받기

2단계: 환경 변수 설정하기

Kimi API 키를 환경 변수로 설정하세요. Kimi API는 Moonshot API 엔드포인트를 사용하므로 다음 변수를 설정해야 합니다:

export MOONSHOT_API_KEY="your-api-key-here"

export MOONSHOT_API_KEY="your-api-key-here"

API 기본 URL은 다음과 같습니다:

https://api.moonshot.ai/v1

https://api.moonshot.ai/v1

3단계: 의존성 설치

Deep Agents와 필요한 LangChain 의존성을 설치하세요:

pip install deepagents langchain-openai
``````bash
pip install deepagents langchain-openai

Kimi API는 OpenAI와 호환되므로 langchain-openai를 사용하면 LangChain이 OpenAI 호환 인터페이스를 통해 Kimi 모델에 연결할 수 있습니다.

Deep Agent에 웹 검색 기능을 추가하려면 선택적으로 Tavily를 설치할 수 있습니다:

pip install tavily-python

pip install tavily-python

Tavily 플랫폼에서 Tavily API 키를 생성한 후, 이를 환경 변수로 설정하세요:

export TAVILY_API_KEY="your-tavily-api-key"

export TAVILY_API_KEY="your-tavily-api-key"

에이전트에 웹 검색 도구를 추가할 계획이 있는 경우에만 Tavily가 필요합니다.

4단계: Kimi API로 Deep Agent 구성

Kimi API는 OpenAI API 형식과 호환되므로 init_chat_model을 통해 LangChain Deep Agents에 연결할 수 있습니다.

다음 예시는 Kimi로 구동되는 기본 Deep Agent를 생성합니다. 필요에 따라 웹 검색과 같은 도구를 추가하여 확장할 수 있습니다.

Kimi 기반 기본 Deep Agent

from os import environ from deepagents import create_deep_agent from langchain.chat_models import init_chat_model kimi_model = init_chat_model( "kimi-k3", api_key=environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1", temperature=0.7, ) agent = create_deep_agent( model=kimi_model, system_prompt="""You are an expert assistant. Your job is to solve tasks with structured reasoning and provide clear outputs. """, )

웹 검색 기능 추가(선택)

웹 검색을 활성화하려면 Tavily와 같은 검색 도구를 연결하세요:

from tavily import TavilyClient tavily_client = TavilyClient( api_key=os.environ["TAVILY_API_KEY"] ) def internet_search(query: str, max_results: int = 5): """Run a web search""" return tavily_client.search( query=query, max_results=max_results ) agent = create_deep_agent( model=kimi_model, tools=[internet_search], system_prompt="""You are an expert researcher. Use the internet search tool when additional information is required. """, )

이 구성을 사용하면 Deep Agents는 Kimi를 추론 모델로 사용하면서 Tavily를 통해 외부 검색 기능에 접근할 수 있습니다.

5단계: Kimi 기반 Deep Agent 실행

Deep Agent를 Kimi로 구성한 후, 에이전트를 실행하여 작업 처리 방식과 도구 호출을 테스트해 보세요.

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is LangGraph?"}]}
)

print(result["messages"][-1].content)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is LangGraph?"}]}
)

print(result["messages"][-1].content)

6단계: LangSmith 추적 활성화(선택)

LangSmith 추적은 도구 호출, 중간 단계, 모델 응답 등 에이전트 실행 과정을 모니터링하는 데 도움이 됩니다.

다음 환경 변수를 사용하여 추적을 활성화하세요:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

에이전트 워크플로에 대한 더 깊은 가시성, 디버깅, 성능 분석이 필요할 때 LangSmith를 사용하세요.

Kimi API로 에이전트 연결하기

Kimi API 사용의 이점

Kimi API를 Deep Agents와 연결하면 복잡한 워크플로를 더 강력하고 관리하기 쉽게 만들 수 있습니다. 이 조합은 에이전트에 더 강력한 추론 능력을 부여하면서도 도구를 사용하고 파일을 처리하며 여러 작업을 수행할 수 있게 해줍니다. 이 구성이 제공하는 주요 이점을 살펴보겠습니다:

에이전트 추론 및 작업 실행 향상

Kimi 모델은 강력한 언어 이해 및 추론 능력을 제공하여 Deep Agents가 복잡한 지시를 분석하고 작업을 세분화하며 더 정확한 응답을 생성하도록 돕습니다. 이를 통해 에이전트는 수동 가이드를 줄이면서도 다단계 워크플로를 더 효과적으로 처리할 수 있습니다.

더 강력한 AI 워크플로 구축

Kimi API를 Deep Agents에 연결하면 개발자는 Kimi의 모델 능력을 LangChain이 지원하는 도구, 파일 시스템, 외부 통합과 결합할 수 있습니다. 이를 통해 에이전트는 통합된 워크플로 내에서 연구, 문서 처리, 코드 분석, 데이터 처리 같은 작업을 수행할 수 있습니다.

자율 에이전트로 복잡한 작업 확장

Kimi 기반 Deep Agents는 계획을 세우고 도구를 사용하며 필요할 때 하위 작업을 위임함으로써 장시간 실행되는 작업을 관리할 수 있습니다. 이를 통해 반복적인 수동 작업을 줄이면서 복잡한 워크플로를 완료할 수 있는 AI 애플리케이션을 더 쉽게 구축할 수 있습니다.

결론

신뢰할 수 있는 AI 에이전트를 만드는 첫걸음은 복잡한 워크플로에 적합한 기반을 선택하는 것입니다. LangChain Deep Agents는 계획을 세우고, 도구를 사용하고, 컨텍스트를 관리하고, 여러 단계로 이루어진 작업을 수동 작업 없이 처리할 수 있는 에이전트를 만드는 데 필요한 도구와 구조를 제공합니다. 적절한 모델과 구성을 갖추면 개발자는 고급 에이전트 아이디어를 실제 애플리케이션으로 구현할 수 있습니다. Kimi API를 통합하면 강력한 추론 능력과 긴 컨텍스트 처리 능력으로 Deep Agent 워크플로를 한층 강화할 수 있습니다. Kimi API를 살펴보고 AI 에이전트로 무엇을 만들 수 있는지 알아보세요.

Kimi API 키 받기

자주 묻는 질문

LangChain 에이전트와 Deep Agents의 차이는 무엇인가요?

LangChain 에이전트는 도구를 활용하는 AI 에이전트를 구축하기 위한 기반을 제공합니다. Deep Agents는 이 기반 위에 계획 수립, 파일 관리, 서브에이전트 위임, 컨텍스트 처리 같은 추가 기능을 더합니다. 이러한 기능들은 Deep Agents가 더 길고 복잡한 작업에 적합하도록 만들어 주며, 이런 기능을 따로 구축해야 하는 필요성도 줄여줍니다.

LangChain Deep Agents는 어디에 사용할 수 있나요?

LangChain Deep Agents는 여러 단계, 도구 사용, 지속적인 의사 결정이 필요한 작업을 처리할 수 있습니다. 연구 자동화, 문서 분석, 코드 이해, 데이터 처리, 복잡한 워크플로 실행 같은 사용 사례를 지원할 수 있습니다. 여러 전문 영역이 관련된 작업의 경우, Deep Agents는 특정 하위 작업을 전문 서브에이전트에 위임하고 그 결과를 결합할 수 있습니다. Deep Agents를 Kimi API와 연결하면 개발자는 Kimi의 추론 능력과 큰 컨텍스트 윈도우를 활용하는 AI 애플리케이션을 구축할 수 있습니다. 예를 들어 방대한 문서 분석, 복잡한 정보 처리, 지식 집약적 워크플로 자동화 같은 작업이 가능합니다.

LangChain Deep Agent에 메모리를 추가할 수 있나요?

네, LangChain Deep Agents는 사용 가능한 지속성 및 메모리 통합을 통해 메모리를 지원할 수 있습니다. 이를 통해 에이전트는 매번 처음부터 시작하지 않고 상호작용과 작업 간에 관련 정보를 유지할 수 있습니다. 메모리는 개인화된 워크플로, 장기 실행 작업, 지속적인 정보 유지에 유용할 수 있습니다.

다음도 마음에 드실 수 있습니다