Claude 도구 API 정식 출시
에이전트에게 "이 PDF 읽고 저 웹 포털에 대신 입력해 줘"를 시키는 데 필요한 조각이 셋인데, 그 셋이 같은 날 정식 출시됐습니다. 2026년 8월 20일입니다.
Anthropic이 computer use, Skills API, Files API 세 가지의 정식 출시를 발표했습니다. 각각 따로 보면 기능 추가인데, 셋을 붙여 놓으면 성격이 달라집니다.
세 조각이 각각 맡는 일
발표문이 든 예시가 구성을 잘 보여 줍니다. 보험 청구 처리 에이전트입니다. Files API에서 접수 문서를 읽고, 팀의 접수 절차를 담은 skill을 따라, browser use tool로 보험사 웹 포털에서 제출을 마치고, 확인서를 다시 파일로 저장합니다.
| 조각 | 맡는 일 |
|---|---|
| Files API | 에이전트가 읽고 쓰는 문서의 저장소 |
| Skills API | 팀의 절차를 코드와 문서로 묶어 올려 두는 곳 |
| computer use | 화면을 보고 클릭하고 입력하는 손 |
| browser use tool | 웹 애플리케이션 전용 손 |
역할 분담이 사람의 업무 구조와 닮았습니다. 문서, 절차서, 그리고 소프트웨어를 조작하는 손입니다. 지금까지는 이 셋 중 손 쪽이 가장 불안했습니다.
computer use: 도구 식별자가 toolset으로 바뀌었다
여기가 실무에서 가장 먼저 걸리는 부분입니다. 도구 타입 문자열이 바뀌었습니다.
{
"type": "computer_toolset_20260801",
"name": "computer"
}
Claude API에서는 beta 헤더가 필요하지 않습니다. 이전 버전인 computer_20251124는 anthropic-beta: computer-20251124-api 헤더가 필요했고, 지금은 구형 모델용으로 남았습니다.
지원 모델이 갈립니다. computer_toolset_20260801은 claude-opus-5, claude-sonnet-5, claude-opus-4-8, claude-fable-5, claude-mythos-5에서 동작합니다. Opus 4.7과 4.6, Sonnet 4.6, Opus 4.5는 이전 computer_20251124를 써야 합니다.
파라미터에서 사라진 게 하나 있습니다. 화면 너비와 높이입니다. 이전 버전은 display_width_px 같은 값을 받았는데, computer_toolset_20260801은 받지 않습니다. 좌표를 돌려주는 스크린샷에서 직접 읽습니다. 기존 코드를 옮길 때 이 두 파라미터를 그대로 두면 거부됩니다.
이름이 tool에서 toolset으로 바뀐 이유는 안에 든 것이 하나가 아니기 때문입니다. member tool이 17개입니다.
| 분류 | member |
|---|---|
| 화면 읽기 | screenshot, zoom |
| 클릭 | left_click, right_click, middle_click, double_click, triple_click |
| 포인터 | mouse_move, left_click_drag, left_mouse_down, left_mouse_up, cursor_position |
| 스크롤 | scroll |
| 키보드 | type, key, hold_key |
| 대기 | wait |
zoom이 눈에 띕니다. 지정한 영역을 원본 해상도로 다시 캡처합니다. 전체 화면 스크린샷은 축소되어 작은 글자를 놓치기 쉬운데, 그 문제를 영역 재촬영으로 풉니다. hold_key와 wait는 최대 300초까지 받습니다.
turn당 한 동작에서 여러 동작으로
베타에서 정식 출시로 오면서 가장 크게 바뀐 지점입니다. 이전에는 모델 호출 한 번에 동작 하나였습니다. 지금은 한 응답에 여러 tool_use 블록을 담습니다.
로그인 폼을 채우는 작업을 생각해 보면 차이가 큽니다. 아이디 칸 클릭, 입력, 비밀번호 칸 클릭, 입력, 로그인 클릭이면 모델 호출 5회였던 것이 1회가 됩니다. 지연과 비용이 함께 줄어듭니다.
대신 실패 처리 규칙을 알아야 합니다. 동작은 순서대로 실행되고 첫 실패에서 멈춥니다. 실행되지 않은 나머지 동작에는 이런 결과를 돌려줘야 합니다.
{
"type": "tool_result",
"tool_use_id": "toolu_01...",
"toolset_name": "computer",
"is_error": true,
"content": "Not executed: an earlier computer action in this turn failed."
}
toolset_name 필드가 모든 결과에 들어가야 합니다. 값은 "computer"입니다. 예전 방식으로 tool_use_id와 content만 채우면 통과하지 않습니다.
한 동작씩 진행하고 싶으면 병렬 도구 사용을 끕니다.
{
"tool_choice": { "type": "tool", "disable_parallel_tool_use": true }
}
화면 상태를 매 단계 확인해야 하는 작업이라면 이쪽이 안전합니다. 화면이 예상과 달라졌는데 나머지 클릭이 그대로 나가면 엉뚱한 곳을 누릅니다.
browser use tool은 여기서 한 겹 더 갑니다. 픽셀 좌표만 쓰는 것보다 웹 요소를 안정적으로 겨냥하도록 페이지 구조 분석을 더했습니다. 웹 애플리케이션만 다룰 거라면 이쪽이 맞습니다.
의료 쪽 이야기도 붙었습니다. computer use가 BAA 아래 HIPAA 규제 대상 워크로드에 쓸 수 있게 됐습니다.
Skills API: skill이 저장 객체가 됐다
Claude Code의 Skills를 다룬 적이 있는데, 그때는 로컬 디렉터리에 마크다운 파일을 두는 구조였습니다. 이제 API 층으로 올라와 저장되고 버전이 붙는 객체가 됐습니다.
skill은 지시문과 스크립트, 템플릿이 든 폴더입니다. 작업이 필요할 때만 Claude가 읽어 들이고, Claude의 코드 실행 sandbox 안에서 돕니다. 직접 호스팅할 서버가 없습니다.
엔드포인트 구성입니다.
POST /v1/skills # 생성 (multipart/form-data)
GET /v1/skills # 목록
GET /v1/skills/{skill_id} # 조회
DELETE /v1/skills/{skill_id} # 삭제
POST /v1/skills/{skill_id}/versions # 새 버전 업로드
GET /v1/skills/{skill_id}/versions # 버전 목록
GET /v1/skills/{skill_id}/versions/{version} # 버전 조회
DELETE /v1/skills/{skill_id}/versions/{version} # 버전 삭제
버전 참조에 latest 리터럴을 쓸 수 있습니다. latest_version_id 필드가 가리키는 곳으로 해석됩니다. 다만 skills-2025-10-02 beta 헤더를 붙인 요청은 버전을 Unix epoch 타임스탬프로 주소지정합니다. 예시가 "1759178010641129" 형태입니다. beta 경로와 정식 경로에서 버전 식별 방식이 다르니 여기서 한 번 헤맬 수 있습니다.
name 필드의 성격이 중요합니다. 첫 업로드의 SKILL.md frontmatter에 있는 name(없으면 그 폴더 이름)에서 kebab-case slug로 정해지고, 이후 바뀌지 않습니다. 나중 업로드도 같은 값으로 해석돼야 합니다. 이 slug가 마운트된 파일의 최상위 디렉터리 이름이 되고, 내려받을 때 아카이브 파일명이 됩니다.
skill의 출처는 네 종류로 구분됩니다.
source.type | 뜻 |
|---|---|
custom | 사용자가 작성. 해당 workspace 전용 |
anthropic | Anthropic 발행. 공유되며 읽기 전용 |
anthropic_example | Anthropic 발행 예제 |
plugin | 설치된 플러그인에서 해석 |
요청에 붙이는 방법에서 혼동이 잘 생깁니다. Skills를 쓰려면 세 가지를 함께 넣습니다.
client.beta.messages.create(
model="claude-opus-5",
max_tokens=16000,
container={"skills": [{"skill_id": "skill_01...", "version": "latest"}]},
tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
messages=[...],
)
container에 skill을 얹고, 코드 실행 도구를 선언하고, beta 두 개를 붙입니다. skill이 sandbox 안에서 도니까 코드 실행 도구가 함께 필요합니다.
Managed Agents와 헷갈리지 않기
여기가 정말 자주 어긋나는 지점입니다. Skills는 Managed Agents가 아닙니다.
Managed Agents는 별개 표면입니다. POST /v1/agents로 에이전트 설정을 저장해 두고, 세션을 만들어 실행합니다. 세션마다 컨테이너가 workspace로 할당되고 에이전트 루프 자체를 Anthropic이 돌립니다. beta 헤더도 다릅니다. managed-agents-2026-04-01입니다.
반면 Skills로 문서를 만들게 하려면 위처럼 client.beta.messages.create에 container와 코드 실행 도구를 얹으면 끝입니다. client.beta.agents나 세션 API를 쓰는 게 아닙니다. Skills가 Managed Agents 안에서도 쓰이기 때문에 문서를 훑다 보면 두 경로가 섞여 보입니다.
Files API: 한 번 올리고 ID로 부른다
성격은 단순합니다. PDF나 스프레드시트를 한 번 올려 두고, 이후 요청에서는 다시 보내지 않고 ID로 참조합니다.
POST /v1/files
beta 헤더는 files-api-2025-04-14입니다. 업로드할 때와, 그 파일을 참조하는 messages.create 양쪽에 모두 붙여야 합니다. 한쪽만 붙이면 실패합니다.
참조할 때는 content block 타입이 파일의 MIME 타입과 맞아야 합니다.
{
"type": "document",
"source": { "type": "file", "file_id": "file_01..." }
}
PDF와 텍스트는 document, 이미지는 image입니다.
정식 출시로 오면서 늘어난 것이 셋입니다. 파일 자동 만료가 들어왔고, rate limit이 5배로 올랐고, 조직당 저장 용량이 1TB가 됐습니다. 자동 만료는 편의 기능처럼 보이지만 실무에서는 정리 부담을 덜어 줍니다. 업로드해 둔 파일을 지우는 코드를 따로 관리하지 않아도 됩니다.
base64로 PDF를 매번 실어 보내는 방식과 비교하면 차이가 분명합니다. base64 경로는 요청 32MB, 600페이지 제한이 걸립니다. 같은 문서를 여러 번 물어볼 거라면 매 요청마다 그 크기를 다시 전송하는 셈입니다.
어디서 쓸 수 있나
플랫폼마다 갈립니다. 세 기능 모두 Claude 플랫폼에서 쓸 수 있습니다. Skills API와 Files API는 Microsoft Foundry에서도 접근됩니다. computer tool과 browser tool은 Google Cloud Vertex AI에 들어올 예정입니다.
computer use는 플랫폼별로 버전이 다릅니다. computer_toolset_20260801 전체 지원은 Claude API고, Claude Platform on AWS와 Bedrock, Google Cloud, Foundry는 이전 버전이 beta로 올라가 있습니다. 특정 클라우드에 묶여 있다면 도구 식별자와 모델을 같이 확인해야 합니다.
무엇이 실제로 달라지나
세 기능의 정식 출시를 하나로 묶으면, 에이전트가 API를 가진 시스템만 다루던 단계에서 벗어난다는 뜻입니다. 화면만 있는 소프트웨어, 예를 들어 사내 레거시 웹 콘솔이나 외부 기관 포털은 자동화 대상이 아니었습니다. 사람이 대신 클릭했습니다.
다만 ClaudeBleed 사례를 다루면서 봤듯이, 브라우저를 조작하는 권한은 그 자체로 공격 표면입니다. 화면을 보고 클릭하는 에이전트에게는 세션 쿠키가 붙은 브라우저가 그대로 열려 있습니다. 웹 포털에 자동 입력을 맡기기 전에, 그 에이전트가 어떤 페이지까지 갈 수 있는지 경계를 먼저 정해 두는 편이 좋습니다.
turn당 여러 동작이 묶이는 변화는 그래서 양면입니다. 비용과 지연이 줄지만, 잘못된 화면 판단 하나가 다섯 번의 클릭으로 번집니다. 되돌리기 어려운 작업에서는 disable_parallel_tool_use를 켜는 쪽이 낫다고 봅니다.
