Claude Agent SDK는 에이전트 루프를 실행하고 MCP로 도구를 호출합니다. 브라우저를 시작하고 결과를 확인하는 일은 도구 처리기가 맡습니다. 이 예제에서는 로컬 페이지에 상태 코드가 표시돼야 작업이 끝납니다.
브라우저 연결 방식 고르기
입력과 완료 조건이 명확한 반복 작업에는 범위가 좁은 도구가 적합합니다. 낯선 화면을 탐색할 때는 일반 Playwright MCP 서버가 유연합니다. Anthropic API SDK의 브라우저 도구 모음에는 별도의 드라이버 인터페이스가 있습니다.
API SDK 도구 모음 문서 · Playwright 연결 문서
브라우저 에이전트 · 브라우저 자동화 · 브라우저 자동화 에이전트
등록과 실행, 작업 결과 나누기
MCP 클라이언트에서 짧은 이름 세 개가 보이면 등록은 성공입니다. 그다음 URL과 상태를 통해 처리기가 어느 페이지를 사용했는지 확인합니다. 마지막으로 호스트가 별도 읽기로 완료 조건을 확인합니다. 문제가 생기면 이 순서로 살펴봅니다.
도구 세 개 구현하기
tool()에서 입력 검사와 처리기를 정의하고 createSdkMcpServer()로 등록합니다. 선택형 에이전트 진입점은 서버를 query().options.mcpServers.fixture에 넣습니다. 동작 이름은 mcp__fixture__reveal_status입니다. 허용 목록에 정확한 이름을 넣고 각 처리기에서 접근 범위를 제한합니다. SDK 사용자 도구 문서
Playwright는 로그인 정보가 없는 새 컨텍스트를 시작합니다. 두 가지 테스트 모드만 받고 로컬 테스트 페이지와 동일한 출처에서만 이동합니다. 버튼의 접근성 이름을 정확히 검색합니다. 하나만 찾았을 때 클릭한 뒤 상태 영역을 읽습니다.
| 도구 | 확인된 결과 |
|---|---|
open_fixture({variant}) | Status code hidden |
read_status() | 변경 없이 읽은 페이지 상태 |
reveal_status() | Status code: SDK-17 |
실행 순서대로 소스 읽기
fixture.mjs에서 테스트 모드 두 가지를 확인합니다. browser-tools.mjs에는 역할 선택자, 상태 읽기, 호출 한도가 있습니다. 마지막으로 smoke.mjs를 읽습니다. 메모리 내 MCP 클라이언트는 선택형 에이전트와 같은 처리기를 호출합니다. 먼저 이 테스트로 도구 실패와 모델 문제를 구분하세요.
로컬에서 예제 실행하기
스모크 테스트는 메모리 전송으로 실제 SDK MCP 서버에 연결해 결정적인 MCP 클라이언트로 로컬 Chromium을 제어합니다. 모델 자격 증명 없이 실행했습니다. 선택형 에이전트 진입점은 승인된 API 키가 필요하며 이번에는 실행하지 않았습니다.
npm ci
npx playwright install chromium
npm test정상 흐름과 오류 흐름 따라가기
첫 호출은 정상 페이지를 열고 두 번째는 코드를 표시하며 세 번째는 표시된 값을 읽습니다. 이어 버튼이 없는 페이지를 열고 작업 실패와 코드가 계속 숨겨졌는지를 별도 읽기로 확인합니다. 이후에는 읽기 호출로만 한도에 도달합니다.
도구 응답 읽기
오류용 테스트 페이지에는 버튼이 없습니다. 도구는 일치 항목 0개와 숨겨진 상태를 반환합니다. 별도의 페이지 읽기로 코드가 나타나지 않았음을 확인했습니다. 아홉 번째 호출은 예산 오류를 반환합니다. 화면은 페이지 상태를 보여주고 JSON은 도구의 응답을 기록합니다.
{
"isError": true,
"ok": false,
"code": "TARGET_MISSING_OR_AMBIGUOUS",
"expected": "Reveal status code",
"matches": 0,
"observed": "Status code hidden"
}
동작이 실행되는 곳에서 범위 제한하기
예제는 로컬 출처 한 곳, 모드 두 가지, 버튼 하나로 제한됩니다. 다른 페이지로 바꿀 때도 같은 수준의 경계를 유지합니다. 페이지의 콘텐츠는 데이터이며 도구 권한을 바꿀 수 없습니다. 페이지가 제공한 선택자, 스크립트, 목적지를 그대로 사용하지 말고 쓰기를 추가하기 전에 허용 필드와 환경을 정합니다.
중단 기준 정하기
대상이 없거나 여러 개라면 페이지 상태를 보관하고 선택자를 확인합니다. 클릭 이후 상태가 바뀌지 않았다면 재시도 전에 페이지를 읽습니다. 호출 예산이 소진되면 멈추고 마지막으로 확인된 결과를 남깁니다. 쓰기를 재시도하기 전에는 저장된 값을 먼저 확인합니다.
| 실패 | 다음 단계 |
|---|---|
TARGET_MISSING_OR_AMBIGUOUS | 선택자 확인 |
POSTCONDITION_FAILED | 페이지 다시 읽기 |
TOOL_BUDGET_EXHAUSTED | 중단 후 마지막 결과 보관 |
한 Claude Code 사용자는 브라우저 동작이 보이지 않았는데도 양식 테스트가 성공했다고 보고된 사례를 설명했습니다. 다른 글에서는 검증 오류가 보였는지와 다음 동작이 실행되지 않았는지를 모두 확인하자는 제안이 나왔습니다. 이 사례를 바탕으로 독립적인 확인을 넣었습니다. r/ClaudeCode · r/AI_Agents
선택자를 바꾸기 전에 진단하기
페이지가 열리지 않았거나 버튼이 없거나 클릭 후 앱이 상태를 바꾸지 않았을 수 있습니다. 오류 코드와 관찰한 상태를 함께 보관합니다. 결정적 클라이언트에서 재현된다면 모델 지시를 바꾸기 전에 처리기나 테스트 페이지를 수정합니다.
모델 밖에서 결과 확인하기
선택형 진입점은 기본 도구를 비활성화하고 지정된 이름 세 개만 허용합니다. 시간과 턴 수도 제한합니다. 모델이 성공으로 보고해도 호스트가 페이지를 별도로 확인합니다. 적용할 때는 새로고침 뒤 저장값을 읽는 식으로 독립적인 검증을 추가하세요.
npm run agent작은 작업부터 옮기기
테스트 출처와 명확한 업무 완료 조건을 정하고 입력 스키마를 좁게 유지합니다. 호출 한도를 두고 동작 이름, 고정 오류 코드, 검증 요약을 기록합니다. 공유 로그에 자격 증명, 사용자 정보, 원본 양식 값을 담지 않습니다. 작은 흐름이 반복 검증된 뒤 범위를 넓힙니다.
자주 묻는 질문
어느 구성 요소가 브라우저를 시작하나요?
도구 호스트의 로컬 Playwright 어댑터가 시작합니다.
스모크 테스트에 API 키가 필요한가요?
필요 없습니다. 클라이언트가 SDK에 등록된 도구를 직접 호출합니다.
임의의 주소를 보낼 수 있나요?
테스트 모드 두 개만 받으며 이동은 테스트 페이지와 같은 로컬 출처로 제한합니다.
클릭 후에 왜 확인해야 하나요?
클릭이 실행돼도 앱이 기대한 상태로 바뀌지 않을 수 있습니다.
Playwright MCP와 어떤 차이가 있나요?
일반 서버는 재사용 가능한 브라우저 동작을 제공합니다. 이 예제는 결과를 정의한 전용 도구 세 개를 제공합니다.
실제 양식에 바로 연결할 수 있나요?
합성 데이터로 먼저 확인하고 쓰기 권한과 독립 검증을 마련하세요.