LLM Wiki

Auto-Deep-Research — AutoAgent 기반 완전 자동화 딥리서치 어시스턴트

Properties3
descriptionAutoAgent의 MetaChain 루프·웹/파일/코딩 에이전트·Docker 브라우저 환경을 묶은 딥리서치 앱.
tagsai-agents, ai-coding, deep-research, browser-automation, rag, python, docker
aliasesAuto-Deep-Research, 자동 딥리서치

13 min read

Auto-Deep-Research는 AutoAgent 프레임워크를 기반으로, LLM 호출·도구 호출·웹 탐색·파일 처리·코딩 실행 환경을 하나의 대화형 딥리서치 제품으로 묶은 오픈소스 저장소다. README의 제품 포지셔닝과 고정 커밋의 실제 코드 구조를 분리해 기록한다.

한눈에 보기

  • 프로젝트 성격: OpenAI Deep Research의 오픈소스·비용 효율 대안으로 소개되는 개인 AI 어시스턴트.
  • 고정 기준: main의 9d671a334d22d58b34ea12af08994af393bbe685 (Update Communication.md, 2025-10-16).
  • 구현 언어/패키징: Python, Python >=3.10, setup.cfg 버전 0.1.3, console entry point auto = autoagent.cli:cli.
  • 주 실행 명령: auto deep-research. CLI가 Docker 기반 코드 환경, BrowserGym/Playwright 기반 브라우저 환경, 파일용 markdown browser를 만든 뒤 대화 루프를 시작한다.
  • 모델 연결: LiteLLM을 통해 function-calling과 non-function-calling 두 경로를 제공한다. README는 OpenAI, Anthropic, DeepSeek, vLLM, Grok, Hugging Face 등 여러 공급자를 예시로 든다.
  • 라이선스 상태: setup.cfg는 MIT를 선언하지만 GitHub API의 license snapshot은 null이고 고정 커밋의 루트 tree에도 LICENSE 파일이 보이지 않는다. 따라서 이 ingest에서는 MIT를 확정 사실로 승격하지 않는다.
  • 검증 상태: 설치·Docker 이미지 pull·브라우저 실행·API 인증·모델 호출·서버 실행·benchmark·보안 테스트는 수행하지 않았다.

공식 README가 말하는 제품 기능

다음 항목은 저장소 README의 제품 설명이며, 이 환경에서 재현한 결과가 아니다.

  • GAIA Benchmark에서 좋은 성능을 낸다고 소개한다.
  • function-calling과 non-function-calling LLM을 모두 지원한다고 설명한다.
  • 자체 API key를 사용하는 pay-as-you-go 방식으로 Deep Research의 월 구독 비용보다 저렴한 대안을 지향한다.
  • 파일 업로드/파일 상호작용을 지원한다고 설명한다.
  • auto deep-research 한 줄로 시작하는 zero-configuration 경험을 제공한다고 주장한다.
  • Docker가 에이전트와 상호작용하는 환경을 컨테이너화하며, 머신 아키텍처에 맞는 사전 빌드 이미지를 자동으로 가져온다고 설명한다.
  • README에는 기본 컨테이너 이름 deepresearch, 기본 포트 12346, DEBUG, API_BASE_URL, FN_CALL, 그리고 기본 completion model로 claude-3-5-sonnet-20241022가 문서화되어 있다. 기본값의 최종 소스인 constant.py는 이번 선택 캡처에 포함하지 않았으므로 해당 값은 README 문서 주장으로 취급한다.

실행 구조

1. MetaChain 오케스트레이션 루프

autoagent/core.py의 MetaChain은 현재 agent와 대화 history를 유지하면서 다음 사이클을 반복한다.

  1. agent instructions와 예시 대화를 context variables에 맞춰 구성한다.
  2. agent 함수 목록을 OpenAI-compatible tool schema로 변환한다.
  3. FN_CALL=True이면 LiteLLM function-calling 경로를 사용한다.
  4. FN_CALL=False이면 도구 설명을 자연어 프롬프트에 삽입하고 모델 응답을 다시 tool-call 형식으로 변환한다.
  5. 모델이 반환한 tool call을 함수명으로 매핑하고, context_variables를 숨겨진 인자로 주입한다.
  6. 도구가 Result를 반환하면 메시지·이미지·context variables·다음 agent를 history에 반영한다.
  7. case_resolved 또는 case_not_resolved tool call을 종료 신호로 사용한다.

동기 run()과 streaming run_and_stream()이 있으며, 네트워크/API 계열 오류에는 최대 4회 exponential retry가 걸려 있다. retry와 종료 동작은 source inspection으로 확인했지만 실제 LLM 호출로 검증하지 않았다.

2. System Triage Agent와 전문 agent

system_triage_agent.py는 사용자의 요청을 다음 전문 agent로 전달하는 허브다.

  • File Surfer Agent: 로컬 파일 형식과 파일 내용을 여는 역할
  • Web Surfer Agent: 브라우저를 통해 웹 페이지를 방문하고 탐색하는 역할
  • Coding Agent: 파일을 만들고 Python 코드·명령을 실행하는 역할

각 agent는 Result(value=..., agent=...)로 대화를 넘기고, 작업이 끝나면 transfer_back_to_triage_agent로 복귀한다. 초기 triage tool 목록에는 case_resolved와 case_not_resolved가 포함된다. 이 구조는 다중 agent 협업의 기본 골격을 제공하지만, 실제 라우팅 품질은 사용 모델의 tool-call 능력과 prompt에 의존한다.

3. CLI와 환경 생성

autoagent/cli.py의 deep-research command는 다음을 수행한다.

  • 컨테이너 이름/포트를 설정하고 .port_lock으로 포트 충돌을 관리한다.
  • DockerEnv를 만들고 컨테이너를 초기화한다.
  • BrowserEnv를 만들고 BrowserGym/Playwright 상호작용을 준비한다.
  • RequestsMarkdownBrowser를 file environment로 만들어 다운로드·파일 텍스트를 다룬다.
  • working_dir, code_env, web_env, file_env를 context variables로 묶는다.
  • PromptSession으로 사용자 질의를 받아 agent를 선택하고 MetaChain.run()을 반복 호출한다.
  • @AgentName 멘션으로 triage agent의 하위 agent를 직접 지정할 수 있다.

환경·도구 계층

Docker 코드 환경

DockerEnv는 로컬 workspace를 컨테이너에 bind mount하고, 통신용 TCP server를 실행하며, 호스트 포트를 컨테이너 포트에 연결한다. run_command()는 localhost TCP socket으로 명령을 보내고 chunk/final JSON 응답을 스트리밍한다. Coding Agent는 Python 실행에는 run_python을 우선 사용하고, 프로젝트 파일은 절대 경로로 읽고 쓰도록 지시된다.

소스상 초기화 경계에서 다음 외부 동작이 있다.

  • workspace에 tcp_server.py가 없으면 https://raw.githubusercontent.com/tjb-tech/agent.midware/refs/heads/main/tcp_server.py에서 다운로드한다.
  • 선택 설정에 따라 HKUDS/MetaChain을 인증 정보가 포함된 URL로 clone하고 .env를 복사하는 코드가 있다. 이번 ingest에서는 이 경로를 실행하지 않았고, 인증값은 저장하지 않았다.
  • Docker image 이름과 conda 경로는 constant.py 및 실행 환경 설정에 의존한다.

따라서 이 프로젝트를 실제로 실행할 때는 외부 bootstrap 코드·컨테이너 권한·bind mount 범위·API key 전달 경로를 먼저 고정하고 검토해야 한다.

BrowserGym/Playwright 브라우저 환경

BrowserEnv는 BrowserGym action API와 Playwright를 사용해 페이지 이동·클릭·입력·스크롤·다운로드·DOM/accessibility tree 관찰을 제공한다. Web Surfer Agent는 다음과 같은 tool을 사용한다.

  • click, page_down, page_up
  • history_back, history_forward
  • web_search, input_text, sleep, visit_url
  • get_page_markdown

브라우저 cookie를 환경에 주입하는 코드와 다운로드 파일을 workspace의 downloads로 저장하는 코드가 있다. 실제 cookie 데이터나 인증 사이트 접근은 이번 capture에서 열지 않았다.

파일·터미널 도구

  • 파일 생성/수정: create_file, write_file, chunked base64 전송
  • 파일 조회/목록: read_file, list_files
  • Python/명령 실행: run_python, execute_command
  • 긴 터미널 출력: terminal_page_up, terminal_page_down, terminal_page_to
  • 파일 선택 UI와 markdown 변환 browser helper도 함께 제공한다.

terminal_tools.py는 명령 결과를 임시 파일에 저장한 뒤 RequestsMarkdownBrowser viewport로 돌려주는 흐름을 사용한다. 즉 모델에게 단순 stdout을 그대로 주기보다 페이지 단위로 탐색하게 하는 설계다.

RAG·코드 메모리

autoagent/memory/rag_memory.py의 Memory는 ChromaDB persistent client를 project path의 .sa 아래에 저장한다.

  • 기본 OpenAI embedding: text-embedding-3-small
  • 비-OpenAI 경로: Sentence Transformers all-MiniLM-L6-v2
  • collection에 query, response, 생성 시간을 저장
  • add_query, query, peek, get, delete, count, reset 제공

CodeMemory는 Python/JS/Java/C/C++/HTML/CSS 파일을 읽어 code_memory collection에 넣고, 질의 결과를 LiteLLM 모델로 재순위화하는 CodeReranker를 제공한다.

rag_tools.py는 PDF/DOCX/TXT 파일 또는 directory/zip을 markdown/text로 변환해 최대 4096 token chunk로 vector DB에 저장하고, query_db, modify_query, answer_query, can_answer로 검색·질의 확장·답변 생성을 수행한다. 이 코드는 zip archive를 extractall()로 풀기 때문에, 신뢰할 수 없는 archive를 입력할 때 path traversal 방어를 별도로 검토해야 한다. 이는 코드 기반 보안 검토 포인트이며, 취약점 재현을 수행했다는 뜻은 아니다.

서버/API 경로

autoagent/server.py에는 FastAPI 서버가 있으며 등록된 agent/tool을 동적으로 endpoint로 만든다.

  • GET /agents: 등록 agent의 문서·인자·소스 경로
  • GET /agents/{agent_name}: 특정 agent 정보
  • POST /agents/{agent_name}/run: model, query, context_variables를 받아 MetaChain 실행
  • POST /tools/{tool_name}: 등록 tool 실행
  • 직접 실행 시 0.0.0.0:8000에서 Uvicorn을 시작

캡처한 server.py에는 사용자 인증·권한 분리·rate limit이 보이지 않는다. 이 파일만으로 전체 앱의 보안 상태를 판단할 수는 없지만, 외부 네트워크에 그대로 노출하지 않고 reverse proxy/auth/sandbox 경계를 추가 검토해야 한다.

시작 절차 — README 기준

실행하지 않은 문서 절차는 다음과 같다.

conda create -n auto_deep_research python=3.10
conda activate auto_deep_research
git clone https://github.com/HKUDS/Auto-Deep-Research.git
cd Auto-Deep-Research
pip install -e .
auto deep-research

setup.cfg는 litellm==1.55.0, browsergym==0.13.0, playwright==1.39.0, ChromaDB, Docker/브라우저 관련 패키지, 문서·멀티미디어 처리 패키지 등 광범위한 dependency를 선언한다. 설치 재현성·실제 Docker image·Playwright browser binary의 호환성은 별도 검증이 필요하다.

API key 환경변수 예시는 README와 .env.template에 있으나, 이 위키에는 실제 secret을 저장하지 않았다. 실행 시 필요한 provider만 설정해야 한다.

공식 사실·해석·미검증 범위

고정 커밋에서 직접 확인한 것

  • MetaChain의 동기/streaming/async 실행 경로
  • function-calling과 non-function-calling 변환 경로
  • System Triage Agent의 File/Web/Coding agent 전환
  • DockerEnv, BrowserEnv, LocalEnv와 TCP 기반 명령 전달
  • ChromaDB 기반 Memory/CodeMemory/RAG tool
  • CLI auto deep-research와 FastAPI 동적 endpoint 코드
  • Python 3.10 이상, console entry point, dependency pin 일부

저장소가 주장하지만 재현하지 않은 것

  • GAIA Benchmark 성능
  • Deep Research 대비 비용 효율
  • zero-configuration one-click launch
  • 다양한 provider의 실제 호환성
  • 자동 Docker image pull과 브라우저/파일 상호작용 성공률

이번 ingest에서 하지 않은 것

  • pip install -e ., dependency resolution, import test
  • Docker daemon/image pull/container startup
  • Playwright browser startup, cookie import, website login
  • OpenAI/Anthropic/DeepSeek 등 API key 인증 및 LLM completion
  • auto deep-research 대화 실행, 실제 research report 생성
  • FastAPI server startup와 endpoint 호출
  • pytest 실행 — 고정 recursive tree에서 dedicated test path도 확인하지 못함
  • GAIA/성능 benchmark, security audit, sandbox escape/path traversal 재현

관련 메모

백링크