Python 웹 조사 에이전트를 프레임워크 없이 만든다

이 Python 저장소는 에이전트 프레임워크를 쓰지 않고 웹 조사 에이전트를 한 파일로 구현한다. 위키백과 검색, 페이지 가져오기, 메모 저장·읽기 도구와 실행 반복, 중단 규칙을 갖추며 메모는 실행 사이에도 유지된다. Humanbound 블로그의 「Build an AI agent from scratch in Python」 글에 함께 제공되는 프로젝트다.

OpenAI 호환 엔드포인트를 사용할 수 있으며, uv가 파일 헤더에 명시된 유일한 의존성인 httpx를 설치한다.

export AGENT_API_KEY=... # your key
export AGENT_BASE_URL=https://api.openai.com/v1 # default
export AGENT_MODEL=gpt-4o-mini # default
uv run agent.py "Who coined the term 'prompt injection', and how is it different from jailbreaking?"

실행 기록은 표준 오류(stderr)에, 답변은 표준 출력(stdout)에 나온다. --dump messages.json을 지정하면 전체 메시지 기록을 저장한다. OpenRouter를 쓰려면 AGENT_BASE_URL=https://openrouter.ai/api/v1과 openai/gpt-5.6-luna 같은 모델 ID를 설정한다. Ollama를 이용해 키 없이 로컬에서 실행할 수도 있다.

AGENT_BASE_URL=http://localhost:11434/v1 AGENT_MODEL=llama3.1:8b uv run agent.py "..."

다만 프로젝트 설명에 따르면 소형 로컬 모델은 도구 호출 성능이 약하다. 기록된 실행에서 llama3.1:8b는 페이지를 가져오지 않고 검색 결과 일부만으로 답해 오답을 냈다. PRICE_IN_PER_MTOK과 PRICE_OUT_PER_MTOK을 설정하면 실행 기록에 비용 추정치를 표시한다. 이 값은 청구서가 아니라 API의 usage 수치를 바탕으로 계산한다.

테스트에는 네트워크나 API 키가 필요 없다. 모델 역할은 스크립트로 만든 로컬 서버가 맡는다.

uv run --with httpx --with pytest pytest tests

examples/에는 블로그 글에서 인용한 실행 기록, 답변, 메시지 기록이 있으며, 2026년 10월 23일에 기록됐다. first-attempt/에는 read_notes가 어떤 단어든 일치하도록 수정되기 전 실행이 담겼다. page-sizes.txt는 measure_pages.py에서 가져온 자료이며, 토큰 수는 문자 수를 4로 나눠 계산했다.

기록된 실행은 HTML 추출기, 메모 쿼리, run_tool의 오류 처리를 강화하고 read_notes 도구 설명을 고친 검토 작업보다 앞선다. 설명에 따르면 실행 기록에 나타난 로직은 바뀌지 않았다. postfix/에는 같은 질문에 강화된 코드를 적용한 두 차례 실행이 있으며, 두 번째 실행은 첫 번째 실행에서 저장한 메모를 읽는다.

프로젝트는 이 에이전트가 안전하게 강화된 상태가 아니므로 신뢰하기 전에 코드를 읽어야 한다고 경고한다. 가져온 텍스트는 외부인이 작성했으며 모델을 조종할 수 있고, 적대적인 페이지 때문에 저장된 메모가 이후 실행을 오도할 수 있다. fetch_url은 공개 주소라면 쿼리 문자열로 데이터를 내보낼 수 있는 주소도 요청한다. 비공개 주소와 루프백 주소는 거부하고 리디렉션은 따라가지 않아 각 요청 경로를 검사하지만, 검사 때와 연결 때 도메인 이름을 각각 해석한다. 따라서 악의적인 DNS 서버가 검사 뒤 비공개 주소를 가리키게 하는 DNS 재바인딩이 가능하다. 프로젝트는 실제 배포용 에이전트라면 검사한 주소로 연결해야 한다고 설명한다. 또한 robots.txt를 읽지 않으며 비용은 MAX_STEPS와 TOKEN_BUDGET으로만 제한한다.

Humanbound은 이와 같은 에이전트를 HTTP를 통해 테스트하는 오픈소스 도구다. 도구가 시험할 항목을 자체적으로 찾기 때문에, 테스트 결과가 깨끗하더라도 안전성을 입증하지는 않는다. 라이선스는 Apache-2.0이다.

프로젝트 저장소: research-agent-from-scratch

블로그 글: Build an AI agent from scratch in Python