Anthropic Messages — Tool 카테고리 셋 · Protocol Quest

Anthropic 의 tool-use 이야기에는 나중에 값을 하는 작은 비틀림이 하나 있어. Tool 을 세 갈래 로 나눠. 셋 다 같은 tools 배열에 들어가지만 모양이 서로 달라.

Custom tools — 네가 만든 tool. name, description, input_schema (JSON Schema) 로 정의해. 개발자 95% 가 처음 손대는 게 이거고, 다른 provider 와 생김새도 같아.
Anthropic 이 정의한 tools — Anthropic 이 내보내서 모델이 태어날 때부터 아는 tool 들이야. computer_20250124, text_editor_20250124, bash_20250124. 타입만 적어서 선언하고, schema 는 Anthropic 이 들고 있어. Claude Code 에서 Claude 가 진짜 컴퓨터를 조작할 수 있는 것도 이것들 덕이야 — 동작 하나하나를 따로 가르치지 않아도 되거든.
MCP server tools — Anthropic API 는 MCP server 와 직접 말할 수 있고, 그렇게 받아온 tool 을 custom tool 옆 같은 배열에 나란히 올려. MCP track 에서 다시 만날 거야.

기계적으로 보면 Anthropic 의 loop 는 깔끔해. Tool 과 메시지를 보내면 content block 이 돌아와. Response 의 content 는 list 야. 텍스트는 type: "text", tool 호출은 type: "tool_use" 에 name 과 input 이 실려 있고, 이 input 은 진짜 dict 야 — JSON 문자열이 아니라. Tool 결과는 원래 tool_use.id 를 가리키는 tool_result block 으로 만들어 user 메시지에 담아 돌려줘.

Loop 를 이끄는 권위 있는 신호는 stop_reason 필드야. "end_turn" 이면 모델이 끝냈다는 뜻, "tool_use" 면 tool 을 부르겠다는 뜻, "max_tokens" 면 예산을 다 썼다는 뜻이지. 분기는 여기서 해. 텍스트를 보고는 절대 하지 마.

Code

Anthropic — custom tool 하나로 왕복 한 바퀴·python

import anthropic

client = anthropic.Anthropic()
tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city.",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
    },
}]

def get_weather(location: str) -> str:
    return f"68°F and clear in {location}"

messages = [{"role": "user", "content": "Weather in Seoul?"}]
while True:
    resp = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason == "end_turn":
        break

    results = []
    for block in resp.content:
        if block.type == "tool_use":
            output = get_weather(**block.input)
            results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
    messages.append({"role": "user", "content": results})

print(messages[-1]["content"])

Custom tool 과 Anthropic tool 을 한 배열에 섞기·python

tools = [
    {"type": "computer_20250124", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
    {  # 네 tool, 옆에 나란히
        "name": "lookup_user",
        "description": "Find user by id.",
        "input_schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]},
    },
]

Exercise

Custom tool 하나로 30 줄짜리 Anthropic agent loop 를 짜. 그 다음 같은 tools 배열에 Anthropic 이 정의한 tool 을 (계정에 권한이 있는 text_editor 나 computer) 하나 더 넣어. Prompt 에 따라 모델이 둘 사이를 고르는지 확인해. 새 갈래를 지원하려고 loop 를 손댈 필요가 없었다는 게 핵심이야.

Anthropic Messages — Tool 카테고리 셋

Code

External links

Exercise

Progress

댓글 0