DeerFlow Skill
HTTP API를 통해 실행 중인 DeerFlow 인스턴스와 통신합니다. DeerFlow는 LangGraph 기반의 AI 에이전트 플랫폼으로, 연구, 코드 실행, 웹 브라우징 등을 위한 하위 에이전트를 조율합니다.
아키텍처
DeerFlow는 Nginx 리버스 프록시 뒤에서 두 개의 API 인터페이스를 제공합니다.
| 서비스 | 직접 포트 | 프록시 경로 | 목적 |
|---|---|---|---|
| 게이트웨이 API | 8001 | $DEERFLOW_GATEWAY_URL | REST 엔드포인트 및 임베디드 에이전트 런타임 |
| LangGraph 호환 API | 8001 | $DEERFLOW_LANGGRAPH_URL | 에이전트 스레드, 실행, 스트리밍 |
환경 변수
모든 URL은 환경 변수를 통해 설정 가능합니다. 요청을 보내기 전에 이 환경 변수들을 읽으십시오.
| 변수 | 기본값 | 설명 |
|---|---|---|
DEERFLOW_URL | http://localhost:2026 | 통합 프록시 기본 URL |
DEERFLOW_GATEWAY_URL | ${DEERFLOW_URL} | 게이트웨이 API 기본 URL (모델, 스킬, 메모리, 업로드) |
DEERFLOW_LANGGRAPH_URL | ${DEERFLOW_URL}/api/langgraph | LangGraph API 기본 URL (스레드, 실행) |
curl 호출 시 항상 다음과 같이 URL을 확인하십시오.
# 환경 변수에서 기본 URL 확인 (모든 API 호출 전에 먼저 수행)
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"
사용 가능한 작업
1. 상태 확인
DeerFlow가 실행 중인지 확인합니다.
curl -s "$DEERFLOW_GATEWAY_URL/health"
2. 메시지 보내기 (스트리밍)
이것이 기본 작업입니다. 스레드를 생성하고 에이전트의 응답을 스트리밍합니다.
1단계: 스레드 생성
curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
-H "Content-Type: application/json" \
-d '{}'
응답: {"thread_id": "<uuid>", ...}
2단계: 실행 스트리밍
curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "lead_agent",
"input": {
"messages": [
{
"type": "human",
"content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
}
]
},
"stream_mode": ["values", "messages-tuple"],
"stream_subgraphs": true,
"config": {
"recursion_limit": 1000
},
"context": {
"thinking_enabled": true,
"is_plan_mode": true,
"subagent_enabled": true,
"thread_id": "<thread_id>"
}
}'
응답은 SSE 스트림입니다. 각 이벤트의 형식은 다음과 같습니다.
event: <event_type>
data: <json_data>
주요 이벤트 유형:
metadata—run_id를 포함한 실행 메타데이터values—messages배열이 포함된 전체 상태 스냅샷messages-tuple— 증분 메시지 업데이트 (AI 텍스트 청크, 도구 호출, 도구 결과)end— 스트림 완료
컨텍스트 모드 (context를 통해 설정):
- 플래시 모드:
thinking_enabled: false, is_plan_mode: false, subagent_enabled: false - 표준 모드:
thinking_enabled: true, is_plan_mode: false, subagent_enabled: false - 프로 모드:
thinking_enabled: true, is_plan_mode: true, subagent_enabled: false - 울트라 모드:
thinking_enabled: true, is_plan_mode: true, subagent_enabled: true
3. 대화 이어가기
후속 메시지를 보내려면 2단계의 동일한 thread_id를 재사용하고 새 메시지로 다른 실행을 POST 하십시오.
4. 모델 목록
curl -s "$DEERFLOW_GATEWAY_URL/api/models"
반환값: {"models": [{"name": "...", "provider": "...", ...}, ...]}
5. 스킬 목록
curl -s "$DEERFLOW_GATEWAY_URL/api/skills"
반환값: {"skills": [{"name": "...", "enabled": true, ...}, ...]}
6. 스킬 활성화/비활성화
curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
7. 에이전트 목록
curl -s "$DEERFLOW_GATEWAY_URL/api/agents"
반환값: {"agents": [{"name": "...", ...}, ...]}
8. 메모리 가져오기
curl -s "$DEERFLOW_GATEWAY_URL/api/memory"
사용자 컨텍스트, 사실 및 대화 기록 요약을 반환합니다.
9. 스레드에 파일 업로드
curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
-F "files=@/path/to/file.pdf"
PDF, PPTX, XLSX, DOCX를 지원하며, 자동으로 Markdown으로 변환합니다.
10. 업로드된 파일 목록
curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"
11. 스레드 기록 가져오기
curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"
12. 스레드 목록
curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
-H "Content-Type: application/json" \
-d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'
사용 스크립트
메시지를 보내고 전체 응답을 수집하려면 도우미 스크립트를 사용하십시오.
bash /path/to/skills/claude-to-deerflow/scripts/chat.sh "Your question here"
구현 내용은 scripts/chat.sh를 참조하십시오. 스크립트는 다음을 수행합니다.
- 상태 확인
- 스레드 생성
- 실행 스트리밍 및 최종 AI 응답 수집
- 결과 출력
SSE 출력 파싱
스트림은 SSE 이벤트를 반환합니다. values 이벤트에서 최종 AI 응답을 추출하려면:
- 마지막
event: values블록을 찾습니다. - 해당
dataJSON을 파싱합니다. messages배열에는 모든 메시지가 포함되어 있습니다.type: "ai"인 마지막 메시지가 응답입니다.- 해당 메시지의
content필드가 AI의 텍스트 응답입니다.
오류 처리
- 상태 확인에 실패하면 DeerFlow가 실행 중이 아닙니다. 사용자에게 시작해야 한다고 알리십시오.
- 스트림이 오류 이벤트를 반환하면 오류 메시지를 추출하여 표시하십시오.
- 일반적인 문제: 포트가 열려 있지 않음, 서비스가 아직 시작 중, 구성 오류.
팁
- 빠른 질문에는 플래시 모드를 사용하십시오 (가장 빠르며 계획 없음).
- 연구 작업에는 프로 또는 울트라 모드를 사용하십시오 (계획 및 하위 에이전트 활성화).
- 먼저 파일을 업로드한 다음 메시지에서 참조할 수 있습니다.
- 스레드 ID는 유지됩니다 — 나중에 대화로 돌아갈 수 있습니다.