Kiro Crew 브라우저

선행 학습

Crew의 개념과 아키텍처는 Kiro Crew, 설치·시작은 Kiro Crew 설치 및 시작에서 먼저 확인하세요.

한 줄 요약

Crew는 web_fetch로 "읽기"만 하는 것을 넘어, 실제 웹 페이지를 사람 대신 조작할 수 있습니다. 페이지 이동·클릭·입력·폼 제출·접근성 트리 검사·스크린샷을 수행하며, 대시보드의 Browser 패널에서 같은 페이지를 지켜보다가 사람이 필요한 순간에 직접 넘겨받을 수 있습니다.

"페이지 내용을 가져와 읽기만" 하면 되는 작업(단순 페이지 페치)과 "로그인·클릭·제출이 필요한" 작업은 다릅니다. Crew 브라우저는 후자를 끝까지 수행하는 도구이고, 에이전트는 매 작업마다 "단순 읽기로 충분한가, 아니면 브라우저 조작이 필요한가"를 스스로 판단합니다.

두 가지 실행 경로

Crew의 브라우징에는 두 경로가 있으며, 환경에 따라 자동으로 선택됩니다.

경로	언제 쓰이나	특징
네이티브 패널 (browser MCP 도구)	데스크톱 앱에서 Browser 패널이 세션을 서빙할 때	앱에 내장된 Chromium 뷰를 단일 MCP 도구로 구동. 사람이 같은 화면을 보고 개입 가능
playwright-cli 폴백	네이티브 패널이 없거나 dashboard.use_builtin_browser가 꺼져 있을 때	셸 경로로 전환. 일반 셸 명령과 동일하게 승인 절차를 거침

네이티브 경로는 단일 MCP 도구이며 Playwright 도구 네임스페이스 전체가 아닙니다. op 값으로 navigate, snapshot, click, type, press_key, hover, select_option, screenshot, wait_for, back, console를 노출합니다.

스냅샷 기반 핸드오프 — 왜 중요한가

Crew 브라우저의 핵심 설계는 접근성 트리(페이지 구조)를 모델 컨텍스트에 밀어넣지 않는다는 것입니다.

• CLI 경로는 모든 명령 실행 후 페이지 URL·제목·스냅샷 YAML 파일 경로를 stdout으로 출력합니다. 약 250자 분량으로 한 번의 액션 결과가 요약되고, 접근성 트리 전체는 에이전트가 필요하다고 판단할 때까지 디스크에 남습니다.
• 그래서 별도의 압축 레이어가 없습니다. YAML을 읽어 요약하는 래퍼를 두면 트리가 다시 컨텍스트로 들어오므로, 디스크 핸드오프가 없애려던 비용을 되살리게 됩니다.

이것은 Context Engineering의 "컨텍스트 예산" 사고와 정확히 같은 철학입니다. 큰 산출물은 디스크에 두고 경로(reference)만 들고 다니며, 필요할 때만 로드합니다.

에이전트가 지켜야 하는 불변식

• 출력된 경로가 권위를 가진다. 스냅샷 디렉터리는 게이트웨이가 소유하므로, 에이전트는 경로를 추론하지 않고 stdout이 알려준 정확한 경로를 사용합니다.
• element ref는 스냅샷마다 유효하다. [ref=e5] 같은 참조는 그 스냅샷 안에서만 유효하고, 페이지가 바뀌면 무효화됩니다. 따라서 이동·페이지를 바꾸는 클릭·새로고침 이후에는 반드시 새 snapshot을 찍고 그 스냅샷 기준으로 요소를 지정합니다. (ref 재사용은 조용히 엉뚱한 요소를 건드릴 수 있어 "재시도"가 아니라 "재스냅샷"으로 규칙이 정의됩니다.)
• 세션은 이름을 가진다. -s=<name>으로 세션을 선택하여, 로그인된 컨텍스트와 일회용 컨텍스트를 분리해 공존시킬 수 있습니다.

안전·승인 경계

브라우저 기능은 "실행 권한"과 "승인"을 분리합니다.

• 런처 존재 ≠ 자동 실행 승인. 제품이 관리하는 playwright-cli가 샌드박스에 읽기 전용으로 설치돼 있더라도, 그것만으로 승인 없이 실행되지는 않습니다. 첫 CLI 명령은 일반 모드에서 승인을 요청하며, 운영자는 1회 승인·세션 내 명령 패턴 신뢰·명시적 광역 자동 승인 중에서 선택할 수 있습니다. 모든 신뢰 결정은 감사(audit) 대상이며 deny·거버넌스 게이트의 적용을 계속 받습니다.
• dashboard.use_builtin_browser (기본 true)는 데스크톱 앱에서 네이티브 MCP 경로를 선택합니다. 끄면 허용된 브라우징이 CLI 경로로 라우팅되며, 거버넌스의 capabilities.browse 거부를 덮어쓰지는 않습니다.
• 네이티브 navigate는 공개 HTTP(S) 대상만 자동 구동합니다. loopback·사설·링크로컬·예약 IP, 인코딩된 호스트 등은 자동 이동 대상에서 제외됩니다.

🚨 유의사항

• 브라우저가 로그인 세션을 다루는 만큼, 자동 승인을 광범위하게 켜면 민감한 사이트까지 사람 확인 없이 조작될 수 있습니다. 신뢰 범위는 좁게 유지하세요.
• 게시(publish)처럼 외부에 영향을 주는 작업은 스킬이 프라이버시 검사와 명시적 승인을 요구합니다.

언제 쓰나 — 결정 가이드

상황	권장
공개 페이지의 텍스트/문서를 읽기만 하면 됨	단순 페이지 페치 (브라우저 불필요)
로그인·클릭·폼 제출이 필요한 작업	Crew 브라우저
사람이 중간에 개입할 수 있어야 함	데스크톱 앱 네이티브 패널 경로
헤드리스/서버 환경	playwright-cli 폴백 (승인 절차 포함)

참고 링크

리소스	URL
공식 문서 — Browser	kiro.dev/docs/crew/features/browser/
소스 — browser 모듈 스펙	github.com/kirodotdev/KiroCrew — docs/system-specs/modules/browser.md

✅ 핵심 요약

Crew 브라우저 = 실제 페이지를 조작하는 에이전트 도구. 네이티브 패널(사람 개입 가능)과 playwright-cli 폴백(승인 절차) 두 경로를 가지며, 접근성 트리를 디스크에 두고 경로만 주고받아 컨텍스트를 아낍니다. 런처 존재가 곧 실행 승인은 아닙니다.

이 문서의 공식 내용은 라이선스 준수를 위해 재구성·요약되었습니다. 정확한 원문은 위 참고 링크를 확인하세요.