Deep Agents 퀵스타트

Deep Agents 퀵스타트 (Quickstart)

몇 분 만에 첫 딥 에이전트(deep agent)를 만들어볼 수 있는 가이드예요. 파일시스템 도구와 서브에이전트 기능을 갖춘 리서치 에이전트를 만들어서, 리서치를 수행하고 보고서를 작성하는 에이전트를 완성해 봐요.

출처: 공식문서

사전 준비

모델 공급자(Gemini, Anthropic, OpenAI 등)의 API 키가 필요해요. Deep Agents는 tool calling을 지원하는 모델이 필요해요.

1단계: 의존성 설치

pip install deepagents

Google, OpenAI, Anthropic은 내장 웹 검색 도구를 제공해 추가 패키지나 API 키가 필요 없어요. 다른 공급자를 쓰거나 Tavily를 선호한다면 pip install tavily-python도 설치하세요.

2단계: API 키 설정

모델 공급자의 API 키를 환경변수로 내보내요.

export OPENAI_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"   # Tavily를 쓸 때

LangSmith Gateway를 쓰면 대부분의 공급자를 LangSmith로 라우팅하고, 자체 공급자 키를 가져오거나 Gateway Credits로 공급자 키 없이 모델에 접근할 수 있어요.

3단계: 검색 도구 만들기

Google·OpenAI·Anthropic은 서버에서 실행되는 내장 웹 검색 도구를 제공해요. 제공자 도구 dict를 create_deep_agent에 직접 전달하면 돼요.

from deepagents import create_deep_agent
# Google 내장 검색
internet_search = {"google_search": {}}
# OpenAI 내장 웹 검색
internet_search = {"type": "web_search"}
# Anthropic 내장 웹 검색
internet_search = {"type": "web_search_20260209", "name": "web_search"}

Tavily(모든 공급자)를 쓰려면 TavilyClient(api_key=os.environ["TAVILY_API_KEY"])로 함수를 직접 정의해요.

4단계: 딥 에이전트 만들기

검색 도구와 모델을 create_deep_agent에 전달해요. model 문자열은 provider:model 형식이거나 초기화된 모델 인스턴스일 수 있어요.

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[internet_search],
    system_prompt=research_instructions,
)

5단계: LangSmith 트레이싱 설정

LangSmith는 도구 호출, 서브에이전트 위임, LLM 응답을 볼 수 있게 해줘요. smith.langchain.com에서 가입 후 API 키를 만들고 환경변수를 설정하세요.

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

6단계: 에이전트 실행

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

어떻게 동작하나

딥 에이전트는 자동으로:

  • internet_search 도구를 호출해 리서치 수행
  • 파일시스템 도구(write_file, read_file)로 큰 검색 결과를 오프로딩하며 컨텍스트 관리
  • 복잡한 하위 작업을 전문 서브에이전트에게 위임
  • 결과를 종합해 보고서 작성

write_todos로 구조화된 작업 계획을 쓰려면 TodoListMiddleware를 선택(opt-in)하세요.

스트리밍

Deep Agents는 LangGraph 기반의 내장 streaming을 제공해 에이전트 실행을 실시간으로 관찰하고, 도구 호출·도구 결과·LLM 응답을 검토·디버깅할 수 있어요.

더 알아보기 (Learn more)