xport ANTHROPIC_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"
```
**Step 3: 검색 도구 생성**
Tavily를 사용하여 인터넷 검색 도구 구성
**Step 4: Deep Agent 생성**
연구 지침을 포함한 시스템 프롬프트로 에이전트 생성
**Step 5: 에이전트 실행**
```python
result = agent.invoke({"messages": [{"role": "user", "content": "What is langgraph?"}]})
print(result["messages"][-1].content)
```
**무엇이 일어났는가?**
- 자동으로 접근 방식 계획
- write_todos 도구를 사용하여 연구 작업을 분해
- internet_search 도구를 호출하여 정보 수집
- 파일 시스템 도구를 사용하여 큰 검색 결과 오프로드
- 필요시 복잡한 하위 작업을 위해 서브에이전트 생성
- 결과를 일관된 응답으로 종합
### 커스터마이제이션 (Customization)
**모델 선택**
기본적으로 Claude Sonnet 4를 사용합니다. LangChain 모델 객체 또는 모델 식별자 문자열을 전달하여 커스터마이징할 수 있습니다.
**시스템 프롬프트**
각 deep agent는 사용 사례별 커스텀 시스템 프롬프트가 필요합니다. 기본 프롬프트는 계획 도구, 파일 시스템 도구, 서브에이전트 사용에 대한 자세한 지침을 포함합니다.
**도구**
다른 도구 호출 에이전트처럼 deep agent는 최상위 도구 세트에 접근할 수 있습니다.
**기본 제공 도구:**
- write_todos: 에이전트의 할일 목록 업데이트
- ls: 에이전트의 파일시스템에서 모든 파일 나열
- read_file: 에이전트의 파일시스템에서 파일 읽기
- write_file: 에이전트의 파일시스템에 새 파일 작성
- edit_file: 에이전트의 파일시스템에서 기존 파일 편집
- task: 특정 작업을 처리할 서브에이전트 생성
## 핵심 기능 (Core Capabilities)
### 에이전트 하네스 (Agent Harness)
deepagents는 "에이전트 하네스"로 생각할 수 있습니다. 다른 에이전트 프레임워크와 동일한 핵심 도구 호출 루프이지만 기본 제공 도구와 기능이 있습니다.
**파일 시스템 접근:**
- ls: 메타데이터가 포함된 디렉토리의 파일 나열
- read_file: 라인 번호 포함된 파일 내용 읽기
- write_file: 새 파일 생성
- edit_file: 파일의 정확한 문자열 교체 수행
- glob: 패턴과 일치하는 파일 찾기
- grep: 여러 출력 모드로 파일 내용 검색
**대용량 도구 결과 제거:**
도구 호출 결과가 토큰 임계값(기본값: 20,000토큰)을 초과하면 자동으로 파일 시스템으로 덤프하여 컨텍스트 윈도우 포화 방지
**플러그 가능한 저장 백엔드:**
- StateBackend: 메모리 내 임시 저장(단일 스레드 내 지속)
- FilesystemBackend: 실제 디스크의 파일 접근
- StoreBackend: LangGraph의 BaseStore 사용(크로스 스레드 지속)
- CompositeBackend: 다양한 경로를 다양한 백엔드로 라우트
**서브에이전트 위임:**
- 메인 에이전트가 격리된 "서브에이전트" 생성 가능
- 각 서브에이전트는 자체 컨텍스트를 가짐
- 메인 에이전트의 컨텍스트 정리 유지
- 토큰 효율성 향상
**회화 히스토리 요약:**
토큰 사용량이 170,000을 초과할 때 자동으로 이전 회화 히스토리 압축
**중단된 도구 호출 복구:**
도구 호출이 중단되거나 취소된 경우 자동으로 메시지 히스토리 복구
**할일 목록 추적:**
write_todos 도구를 사용하여 구조화된 작업 목록 유지
**Human-in-the-Loop:**
특정 도구 호출에서 에이전트 실행 일시 중지하여 인간 승인/수정 허용
**프롬프트 캐싱 (Anthropic):**
Anthropic의 프롬프트 캐싱 기능으로 중복된 토큰 처리 감소
### 백엔드 (Backends)
Deep agent는 ls, read_file, write_file, edit_file, glob, grep과 같은 도구를 통해 파일시스템 표면을 노출합니다.
**내장 백엔드:**
- StateBackend: 에이전트 상태에서 파일 저장(현재 스레드만 지속)
- FilesystemBackend: 실제 로컬 디스크의 파일 읽기/쓰기
- StoreBackend: LangGraph Store를 사용한 크로스 스레드 저장
- CompositeBackend: 경로를 다양한 백엔드로 라우트
**백엔드 지정:**
```python
agent = create_deep_agent(backend=FilesystemBackend(root_dir="."))
```
**경로 라우팅:**
/memories/ 하위 파일을 StoreBackend로, 나머지는 StateBackend로 라우트
### 서브에이전트 (Subagents)
Deep agent는 작업을 위임하기 위해 서브에이전트를 생성할 수 있습니다.
**서브에이전트 사용 목적:**
- 컨텍스트 격리: 메인 에이전트의 컨텍스트 정리 유지
- 전문화된 도메인: 커스텀 지침 또는 도구 필요한 작업
- 다양한 모델 기능: 다양한 작업에 최적의 모델 선택
- 메인 에이전트 초점 유지
**서브에이전트 구성:**
- name: 고유 식별자
- description: 이 서브에이전트의 역할
- system_prompt: 서브에이전트의 지침
- tools: 서브에이전트가 사용할 도구
- model (선택): 메인 에이전트의 모델 오버라이드
- middleware (선택): 커스텀 미들웨어
**CompiledSubAgent:**
복잡한 워크플로우의 경우 미리 구축한 LangGraph 그래프 사용 가능
**일반 목적 서브에이전트:**
메인 에이전트는 항상 일반 목적 서브에이전트에 접근 가능
- 메인 에이전트와 동일한 시스템 프롬프트
- 메인 에이전트와 동일한 도구
- 컨텍스트 격리용 이상적
### Human-in-the-Loop
민감한 도구 작업은 실행 전 인간 승인이 필요할 수 있습니다.
**기본 구성:**
interrupt_on 파라미터로 도구별 승인 필요 여부 지정
**결정 유형:**
- "approve": 원래 인수로 도구 실행
- "edit": 실행 전 도구 인수 수정
- "reject": 도구 호출 건너뛰기
**필수 요구 사항:**
- 체크포인터 필수 (상태 지속성을 위해)
- 중단 처리 시 같은 thread_id 사용
**다중 도구 호출:**
여러 도구가 승인이 필요할 경우 모두 일괄 처리
**모범 사례:**
- 항상 체크포인터 사용
- 재개할 때 동일한 thread_id 사용
- 결정 순서를 작업 순서와 일치
- 리스크 수준에 따라 구성 조정
### 장기 메모리 (Long-term Memory)
Deep agent는 로컬 파일시스템을 가지고 있지만 기본적으로 단일 스레드 내에서만 지속됩니다. CompositeBackend를 사용하여 특정 경로를 지속 스토리지로 라우트하면 장기 메모리 활성화 가능
**설정:**
```python
def make_backend(runtime):
return CompositeBackend(
default=StateBackend(runtime),
routes={"/memories/": StoreBackend(runtime)}
)
agent = create_deep_agent(
store=InMemoryStore(),
backend=make_backend,
checkpointer=checkpointer
)
```
**작동 방식:**
- 단기(일시적) 파일시스템: 에이전트 상태에 저장(단일 스레드 지속)
- 장기(지속) 파일시스템: LangGraph Store에 저장(모든 스레드 지속)
**경로 라우팅:**
- /memories/ 시작하는 파일: Store에 저장(지속)
- 다른 파일: 임시 상태 저장
**크로스 스레드 지속:**
다양한 스레드에서 /memories/의 파일 접근 가능
**사용 사례:**
- 사용자 선호도 저장
- 자가 개선 지침 업데이트
- 지식 기반 구축
- 연구 프로젝트 상태 유지
**저장소 구현:**
- InMemoryStore: 개발용(재시작 시 손실)
- PostgresStore: 프로덕션용 (지속)
### 미들웨어 (Middleware)
Deep agent는 모듈식 미들웨어 아키텍처로 구축되었습니다.
**기본 미들웨어:**
- TodoListMiddleware: 계획 도구
- FilesystemMiddleware: 파일시스템 도구
- SubAgentMiddleware: 서브에이전트 생성
**각 미들웨어의 역할:**
**TodoListMiddleware:**
- write_todos 도구로 할일 목록 업데이트 제공
- 복잡한 다단계 작업 전에 계획 권장
**FilesystemMiddleware:**
- ls, read_file, write_file, edit_file 도구 제공
- 단기(일시적) 및 장기(지속) 메모리 모두 지원
**SubAgentMiddleware:**
- task 도구로 서브에이전트 생성 가능
- 서브에이전트는 고유한 시스템 프롬프트, 도구, 모델 가능
## CLI 도구 (Command Line Interface)
Deep Agents CLI는 지속 메모리를 가진 에이전트 구축용 터미널 인터페이스입니다.
**기본 기능:**
- 파일 작업: 프로젝트의 파일 읽기, 쓰기, 편집
- 셸 명령 실행: 테스트, 빌드, 의존성 관리, 버전 제어 상호 작용
- 웹 검색: 최신 정보 및 문서 검색(Tavily API 키 필요)
- HTTP 요청: API 및 외부 서비스의 데이터 가져오기
- 작업 계획 및 추적: 복잡한 작업을 개별 단계로 분해
- 메모리 저장 및 검색: 세션 간 정보 저장
- Human-in-the-Loop: 민감한 도구 작업에 인간 승인 필요
**빠른 시작:**
```
export ANTHROPIC_API_KEY="your-api-key"
uvx deepagents-cli
```
**구성 옵션:**
- --agent NAME: 지정된 이름의 에이전트 사용
- --auto-approve: 도구 확인 프롬프트 건너뛰기
- --sandbox TYPE: 원격 샌드박스에서 실행 (modal, daytona, runloop)
**인터랙티브 모드:**
- /tokens: 토큰 사용량 표시
- /clear: 대화 히스토리 지우기
- /exit: CLI 종료
- !명령어: 셸 명령 실행
**메모리 구조 설정:**
~/.deepagents/AGENT_NAME/memories/ 에 마크다운 파일로 정보 저장
- 연구: 시작 전 메모리 검색
- 응답: 확실하지 않을 때 메모리 확인
- 학습: 새 정보 자동 저장
**원격 샌드박스 사용:**
안전성, 격리된 환경, 병렬 실행을 위해 Runloop, Daytona, Modal 지원
)
)