웹·외부

Gajae-Code 에이전트가 네트워크와 외부 서비스에 닿게 해주는 web_search, browser, github 도구.

웹 도구는 Gajae-Code 에이전트를 네트워크와 외부 서비스에 연결합니다 — 검색 엔진, 실제 브라우저, GitHub. 이 도구들은 대부분 자격증명에 의존합니다. 각 provider를 켜는 키는 환경 변수를 보세요.

web_search

web_search는 사용 가능한 첫 검색 provider로 한 질의를 돌려 LLM 형식의 답변, 소스 URL, 선택적 인용을 반환합니다.

입력

필드	타입	설명
`query`	`string`	검색 질의. 디스패치 전 `2020`-`2029` 부분 문자열은 현재 연도로 재작성됩니다.
`recency`	`"day" \| "week" \| "month" \| "year"`	시간 필터. 구현하는 provider만 사용(Brave, Perplexity, Tavily, SearXNG).
`limit`	`number`	반환할 최대 결과 수.
`max_tokens`	`number`	Anthropic, Gemini, Perplexity API 키 모드만 전달.
`temperature`	`number`	위 셋만 전달.
`num_search_results`	`number`	업스트림 검색 폭 요청.

Provider

팬아웃은 없습니다 — provider를 순차적으로 시도해 하나가 성공하면 멈춥니다. 강제 provider가 없으면 자동 체인 순서는:

tavily → perplexity → brave → jina → kimi → anthropic → gemini
→ openai-code → zai → exa → parallel → kagi → synthetic → searxng

provider는 자격증명이 해석될 때만 "사용 가능"합니다. 각자 키나 인증이 필요합니다:

Provider	사용 가능 조건
Tavily	API 키(env 또는 저장된 자격증명).
Perplexity	`PERPLEXITY_COOKIES` → OAuth 토큰 → `PERPLEXITY_API_KEY` / `PPLX_API_KEY`.
Brave	`BRAVE_API_KEY`.
Jina	`JINA_API_KEY`.
Kimi	`MOONSHOT_SEARCH_API_KEY` / `KIMI_SEARCH_API_KEY` / `MOONSHOT_API_KEY` 또는 저장.
Anthropic	Anthropic 인증(모델 웹 검색 도구).
Gemini	Google OAuth(`google-gemini-cli` / `google-antigravity`).
OpenAI code	OpenAI code OAuth 자격증명.
Z.AI	`zai` 자격증명(env 또는 저장).
Exa	`EXA_API_KEY`, 그리고 `exa.enabled` / `exa.enableSearch`가 꺼지지 않아야 함.
Parallel	`parallel` 자격증명.
Kagi	`kagi` 자격증명.
Synthetic	`synthetic` 자격증명.
SearXNG	`searxng.endpoint` 설정 또는 `SEARXNG_ENDPOINT`(셀프 호스트).

사용 가능한 provider가 없으면 web_search는 keyless DuckDuckGo로 폴백합니다. 설정에서 선호 provider를 지정할 수 있습니다. 지정한 provider가 먼저 시도된 뒤 나머지 체인이 이어지고, 마지막에 DuckDuckGo 폴백을 사용합니다. 지원 열거형: auto, exa, brave, jina, kimi, perplexity, anthropic, zai, tavily, kagi, synthetic, parallel, searxng.

출력

텍스트 결과는 다음 순서로 구성됩니다:

response.answer(있는 경우)
## Sources — 소스마다 제목, 경과/날짜, URL, 240자로 절단된 선택 스니펫
## Citations
## Related
해당 시 Search queries 요약

browser

browser는 헤드리스 Chromium 또는 CDP 연결 앱에 대해 Puppeteer 탭을 열고·재사용하고·닫고·스크립트합니다. 탭은 프로세스 전역 맵에 살아 있어서 같은 name은 닫기 전까지 호출 간 재사용됩니다.

액션

action 필드는 open, close, run 중 하나입니다.

액션	주요 필드
`open`	`url`, `viewport`, `wait_until`, `dialogs`, `app` — 탭 획득/재사용.
`close`	`all`, `kill` — 탭 하나 또는 전체 해제.
`run`	`code`(필수) — 탭 안 VM 컨텍스트에서 실행되는 비동기 JS 본문.

공유 필드: name(탭 id, 기본 "main"), timeout(초, 기본 30, 최대 30으로 클램프).

브라우저 종류

헤드리스 — Puppeteer로 로컬 Chromium을 띄우고(첫 사용 시 필요하면 다운로드), 스텔스 패치를 적용하며, 탭마다 새 페이지를 만듭니다. 기본 뷰포트 1365x768, 배율 1.25.

스폰 앱(app.path) — 원격 디버깅으로 실행 파일을 재사용/스폰한 뒤 연결합니다. 스텔스 패치 없음.

연결 브라우저(app.cdp_url) — 이미 실행 중인 CDP 엔드포인트에 연결합니다. close는 연결만 해제합니다.

`tab` API

run 안에서 코드는 원시 Puppeteer page/browser와 tab 헬퍼를 받습니다.

tab 헬퍼: tab.goto(), tab.observe(), tab.screenshot(), tab.extract(), tab.click(), tab.type(), tab.fill(), tab.press(), tab.scroll(), tab.waitFor(), tab.evaluate(), tab.select(), tab.uploadFile(), tab.waitForUrl(), tab.waitForResponse(), tab.id(n).

display(value)로 텍스트, JSON, 또는 { type: "image", data, mimeType } 이미지 콘텐츠를 내보냅니다.

프록시 환경변수는 헤드리스 실행에만 영향: PUPPETEER_PROXY, PUPPETEER_PROXY_BYPASS_LOOPBACK, PUPPETEER_PROXY_IGNORE_CERT_ERRORS. 헤드리스 실행은 탐지된 시스템 Chrome, 그다음 PUPPETEER_EXECUTABLE_PATH, 그다음 Chromium 다운로드 순으로 선호합니다.

github

github는 GitHub CLI(gh) 작업을 디스패치합니다. gh가 PATH에 있을 때만 노출되며, gh auth login으로 인증되어 있어야 합니다.

op 필드가 작업을 선택합니다:

`op`	하는 일
`repo_view`	리포지터리 메타데이터 조회(`repo`, 선택 `branch`).
`pr_create`	PR 생성(`title` 또는 `fill`, 그리고 `body`/`base`/`head`/`draft`/`reviewer`/`assignee`/`label`).
`pr_checkout`	하나 이상의 PR을 전용 worktree로 체크아웃(`pr`, `force`).
`pr_push`	현재/지정 브랜치의 PR head 푸시(`branch`, `forceWithLease`).
`search_issues`	이슈 검색(`query`, `repo`, `limit`).
`search_prs`	PR 검색.
`search_code`	코드 검색.
`search_commits`	커밋 검색.
`search_repos`	리포지터리 검색(질의 범위만, `repo` 없음).
`run_watch`	GitHub Actions run 또는 한 커밋의 전체 run 감시(`run`, `branch`, `tail`).

메모:

검색 limit은 기본 10, 50으로 클램프. 검색 op는 repo를 현재 체크아웃의 owner/repo로 기본 설정합니다. 질의에 이미 repo:/org:/user:/owner: 한정자가 있으면 그대로 씁니다.
pr_checkout은 ~/.gjc/wt/<encoded-repo-root>/pr-<number> 아래에 worktree를 만들고 로컬 브랜치는 항상 pr-<number>입니다. pr_push는 pr_checkout이 git 브랜치 설정에 써둔 푸시 메타데이터를 읽으므로 먼저 실행되어야 합니다.
run_watch만 스트리밍 op입니다. 3초마다 폴링하고 라이브 스냅샷을 냅니다. 실패 시 Full failed-job logs: artifact://<id>를 덧붙입니다. 인라인 리포트는 실패 job별 마지막 tail 줄(기본 15, 최대 200)을 보여줍니다.

단일 이슈/PR 읽기와 PR diff는 여기 op가 아닙니다 — 공유 SQLite 캐시(~/.gjc/cache/github-cache.db, GJC_GITHUB_CACHE_DB로 재정의)를 받치는 issue:// / pr:// 내부 URL 스킴으로 해석됩니다.

대부분의 웹 도구는 자격증명 없이는 닫힌 채로 실패합니다. 모든 검색 provider 키, 브라우저 프록시/실행 파일 변수, GitHub 캐시 설정은 환경 변수를 보세요.

목차