Agent-Reach: 채널·실행·로그인을 묶는 통합 CLI

분석 기준: 14c213405669414492bda0f8d52cc6531d062c45. 기존 8월 설명을 공식 README·패키지·채널·런타임 소스와 비교했습니다. upstream 설치·스크립트·브라우저·모델 호출은 실행하지 않았습니다.

1프로젝트 한줄 요약

Agent-Reach 1.6.0은 웹·동영상·SNS의 검색·읽기 기능을 하나의 CLI와 JSON 결과로 제공하는 Python 도구입니다. 플랫폼별 도구를 설치·관리하고, 채널마다 정의한 동작과 백엔드를 연결합니다. 기본 Python 패키지 자체가 모델을 호출해 추론하는 에이전트는 아닙니다.

기존 8월 문서의 “도구를 연결한 뒤 에이전트가 외부 CLI를 직접 호출한다”는 설명에서 범위가 넓어졌습니다. 현재 입구는 agent-reach <channel> <action>이며 입력 검사·시도 순서·공통 오류·로그인 세션을 런타임이 관리합니다.

2왜 주목받는가

2026-10-28 Daily 9위에서 다시 관측됐습니다. 순위는 사용성·안정성 검증이 아닙니다. 소스에서 볼 차별점은 사이트별 명령·반환 형식의 차이를 공통 계약 안에 넣고, 실패한 작업을 빈 검색 결과로 포장하지 않으려는 설계입니다.

총 14개는 channels/__init__.py의 실제 등록 목록입니다. 예전 RSS·Exa를 독립 채널로 세던 15개 표와 다릅니다. Exa는 현재 Web 등의 백엔드 역할도 하므로 채널 수와 사용 도구 수를 섞지 않습니다.

3기술 스택 전체 지도

과거 문서의 Rich·python-dotenv·browser_cookie3를 현 기본 의존성으로 적지 않습니다. 모델 API는 기본 검색의 공통 필수가 아니지만 YouTube 음성 전사는 Groq/OpenAI, Xiaoyuzhou 전사는 Groq 키 등 별도 조건이 있습니다.

4아키텍처 심화 분석

명령 / URL
   → Channel·Action 선택
   → 인자·timeout 검증
   → 추가/도구/세션 상태 확인
   → 동작에 선언한 백엔드 순서로 실행
   → {schema_version, ok, channel, action,
       backend, items, meta, error}

정책을 채널에, 실행을 dispatcher에 둡니다

Param은 이름·필수 여부·형식·기본값을, Action은 백엔드 이름과 구현 메서드의 순서를 선언합니다. dispatcher는 정의되지 않은 인자, 음수 limit, bool을 정수로 쓰는 입력, 유한하지 않은 timeout을 설치·로그인 준비 전에 거부합니다. 이름만 있는 Channel 하위 클래스로 모든 동작이 자동 등록되는 것은 아닙니다.

재시도할 오류와 멈출 오류를 구분합니다

result.py의 FINAL_CODES에는 NOT_FOUND·BAD_INPUT·PLATFORM_BLOCKED·RATE_LIMITED·NEED_LOGIN·BUSY가 있습니다. 이런 오류는 다른 백엔드로 계속 우회하지 않습니다. TIMEOUT·UPSTREAM_BROKEN 등은 정해진 정책에 따라 처리하고 건강 상태를 기록합니다. 실제 제한은 채널 단위 cooldown으로 관리합니다. 반환의 items: []만 보고 “검색 결과 없음”이라 결론 내리지 말고 ok와 error.code를 함께 읽어야 합니다.

브라우저 세션은 일상 Chrome과 분리됩니다

공식 세션 문서는 연결된 Chrome/OpenCLI가 있을 때 첫 사이트 사용 시 해당 사이트 쿠키만 전용 브라우저로 한 번 복사할 수 있다고 설명합니다. 브라우저 전체·암호 저장소를 복사하는 방식은 아닙니다. 사용자가 직접 로그인했거나 logout/remove한 뒤에는 자동 복사를 반복하지 않습니다. 일반 CLI 도구는 ~/.agent-reach/sessions/<tool>/를 HOME/USERPROFILE로 사용합니다.

현재 TwitterChannel은 OpenCLI만 선언합니다. twitter-cli가 인증 실패 시 브라우저 쿠키를 다시 읽는다는 이유로 사용하지 않는다는 코드 주석이 있습니다. 옛 twitter-cli→OpenCLI→bird 순서를 현재 구조로 안내하면 안 됩니다.

5디렉토리 구조 해부

agent_reach/
├─ cli.py                      프로그램 진입점
├─ config.py                   사용자 설정
├─ channels/
│  ├─ base.py                  Channel·Action·Param
│  ├─ __init__.py              실제 14채널 등록
│  └─ twitter.py · web.py ...  플랫폼별 동작·백엔드
├─ runtime/
│  ├─ dispatch.py · result.py  실행·공통 JSON·오류
│  ├─ tools.py · manage.py     도구 설치·채널 관리
│  ├─ sessions.py             원시 CLI 로그인 디렉터리
│  ├─ browser*.py             전용 브라우저와 동시성
│  ├─ session_reuse.py         사이트별 기존 로그인 복사
│  └─ state.py                관리 상태
├─ backends/                   OpenCLI·브라우저 등 어댑터
└─ skill/                      에이전트 사용 지침
docs/install.md                1.6 설치·업데이트·이전 버전 이전

기존의 core.py → doctor.py 위임 구조를 현재 파일 지도에 남기지 않습니다. 채널에서 actions를 먼저 읽고 dispatcher와 result를 따라가면 “무엇을 할 수 있고 실패를 어떻게 표현하는가”를 확인할 수 있습니다.

6학습 포인트

• 공통 결과 계약: 상위 에이전트가 외부 CLI의 출력 문자열을 매번 파싱하지 않도록 schema_version·오류 코드를 둡니다.
• 선언과 실행 분리: Action의 순서 있는 목록을 바꾸는 것과 범용 런타임을 바꾸는 것을 구분합니다.
• 세션 수명: 소유권이 기록되지 않은 디렉터리를 설치·제거 과정이 덮어쓰지 않는지 읽습니다.
• 동시성·정체: 세션 문서의 같은 플랫폼 2개·전체 4개, 검색 간격·대기 한도를 실제 runtime 파일과 대조하는 과제를 만들 수 있습니다. 이 글은 실측 처리량 보고가 아닙니다.

7하드웨어 / 시스템 요구사항

현재 문서는 모든 채널에 Docker나 동일 Node 최소 버전을 요구하지 않습니다. 확인하지 않은 RAM·디스크·실행 속도 최솟값도 만들지 않습니다. PyPI 동명 패키지는 이 프로젝트가 아니므로 설치 출처를 확인해야 합니다. 검색·읽기 전용이라는 제품 설명과 플랫폼이 자동 접근을 허용한다는 판단은 별개입니다.

8직접 해볼 수 있는 실습 과제

1. 채널·계약 확인 · 기초

PIN=14c213405669414492bda0f8d52cc6531d062c45
git show "$PIN:pyproject.toml"
git show "$PIN:agent_reach/channels/__init__.py"
git show "$PIN:agent_reach/channels/base.py"

완료 기준: 등록 14채널을 level별로 나누고 Action 하나의 Param·backend를 적습니다.

2. 첫 설치·공개 읽기 · 중급

자신의 별도 테스트 환경에서 선택할 수 있는 공식 설치 예시입니다. setup은 도구·스킬을 설치하고 상태를 바꾸므로 실행 전 내용을 확인합니다. 분석에서는 실행하지 않았습니다.

uv tool install https://github.com/Panniantong/Agent-Reach/releases/latest/download/agent-reach.zip
agent-reach setup
agent-reach channels
agent-reach read https://www.v2ex.com/t/123

마지막 URL은 문서에 나온 명령 형식 예시이며 특정 게시물의 존재·접근 성공을 보장하지 않습니다. 자신이 확인한 공개 URL로 바꾸고 반환 JSON의 ok·backend·출처를 기록합니다. 처음부터 개인 계정이나 SNS 쿠키를 넣을 필요는 없습니다.

3. 실패를 분류하는 소비자 설계 · 중급

가상의 JSON fixture에 ok:false·RATE_LIMITED, ok:false·NEED_LOGIN, ok:true·items:[]를 각각 만듭니다. 완료 기준: 대기·사용자 로그인·빈 결과를 서로 다른 상태로 표시하는 설계표를 작성합니다. 실제 플랫폼 요청 없이 할 수 있습니다.

4. 로그인 수명 표 · 심화

git show "$PIN:agent_reach/runtime/sessions.py"
git show "$PIN:agent_reach/skill/references/sessions.md"
git show "$PIN:agent_reach/channels/twitter.py"

기존 로그인 복사·직접 로그인·logout/remove 이후 상태를 표로 적습니다. 완료 기준은 재로그인이나 전체 쿠키 추출을 자동으로 반복하지 않아야 할 조건을 설명하는 것입니다. 이 과제는 실제 브라우저·비밀번호·쿠키 파일을 읽지 않습니다.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

본문의 소스 근거를 분석 커밋에 고정했습니다.

• README.md
• pyproject.toml
• docs/install.md
• agent_reach/channels/base.py
• agent_reach/channels/__init__.py
• agent_reach/channels/twitter.py
• agent_reach/runtime/dispatch.py
• agent_reach/runtime/result.py
• agent_reach/runtime/sessions.py
• agent_reach/skill/references/sessions.md

2026-10-28 정적 소스 검토. 실제 채널 가용성·설치 성공·로그인·성능은 독립 검증하지 않았습니다.