프로그래매틱 도구 호출

"Programmatic tool calling"(프로그래매틱 도구 호출)을 사용하면 Claude가 각 도구 호출마다 모델을 거치는 왕복을 요구하는 대신, 코드 실행 컨테이너 내에서 도구를 프로그래매틱하게 호출하는 코드를 작성할 수 있습니다. 이를 통해 다중 도구 워크플로의 "latency"(지연 시간)가 줄어들고, 데이터가 모델의 "context window"(컨텍스트 윈도우)에 도달하기 전에 Claude가 데이터를 필터링하거나 처리할 수 있으므로 토큰 소비도 감소합니다. 다단계 웹 리서치와 복잡한 정보 검색을 테스트하는 BrowseComp 및 DeepSearchQA와 같은 에이전트 검색 벤치마크에서, 기본 검색 도구 위에 프로그래매틱 도구 호출을 추가하면 입력 토큰을 24% 적게 사용하면서 성능이 평균 11% 향상되었습니다(동적 필터링을 통한 웹 검색 개선 참조).

직원 20명의 예산 준수 여부를 확인하는 경우를 생각해 보세요. 기존 방식은 20번의 개별 모델 왕복이 필요하며, 그 과정에서 수천 개의 지출 항목을 컨텍스트로 가져옵니다. 프로그래매틱 도구 호출을 사용하면 단일 스크립트가 20번의 조회를 모두 실행하고, 결과를 필터링하여 한도를 초과한 직원만 반환하므로, Claude가 추론해야 하는 대상이 수백 킬로바이트에서 몇 줄로 줄어듭니다.

프로그래매틱 도구 호출에는 도구 버전 code_execution_20260120 이상의 코드 실행 도구가 필요합니다.

빠른 시작

다음은 Claude가 데이터베이스를 프로그래매틱하게 여러 번 쿼리하고 결과를 집계하는 예시입니다. 도구 정의에 allowed_callers: ["code_execution_20260120"]을 추가하면 해당 도구를 코드 실행 내에서 호출할 수 있게 됩니다(allowed_callers 필드 참조):

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

응답은 stop_reason: "tool_use", container ID, 그리고 query_database에 대한 tool_use 블록과 함께 중지되며, 이 블록의 caller 필드는 해당 도구를 호출한 코드 실행을 식별합니다. 코드가 완료될 수 있도록 예시 워크플로의 3단계에 표시된 대로 결과를 반환하세요.

프로그래매틱 도구 호출의 작동 방식

도구를 코드 실행에서 호출 가능하도록 구성하고 Claude가 해당 도구가 필요하다고 판단하면:

1. Claude가 도구를 함수로 호출하는 Python 코드를 작성합니다. 여기에는 여러 도구 호출과 전처리/후처리 로직이 포함될 수 있습니다
2. Claude가 코드 실행을 통해 샌드박스 컨테이너에서 이 코드를 실행합니다
3. 도구 함수가 호출되면 코드 실행이 일시 중지되고 API가 tool_use 블록을 반환합니다
4. 도구 결과를 제공하면 코드 실행이 계속됩니다(중간 결과는 Claude의 컨텍스트 윈도우에 로드되지 않습니다)
5. 모든 코드 실행이 완료되면 Claude가 최종 출력을 받고 작업을 계속합니다

이 접근 방식은 특히 다음과 같은 경우에 유용합니다:

• 대용량 데이터 처리: 도구 결과가 Claude의 컨텍스트에 도달하기 전에 필터링하거나 집계합니다
• 다단계 워크플로: 도구 호출 사이에 Claude를 샘플링하지 않고 도구를 순차적으로 또는 루프에서 호출하여 토큰과 지연 시간을 절약합니다
• 조건부 로직: 중간 도구 결과를 기반으로 결정을 내립니다

핵심 개념

allowed_callers 필드

allowed_callers 필드는 어떤 컨텍스트에서 도구를 호출할 수 있는지 지정합니다:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

가능한 값:

• ["direct"] - Claude가 이 도구를 직접 호출하도록 안내됩니다(생략 시 기본값)
• ["code_execution_20260120"] - Claude가 이 도구를 코드 실행 내에서만 호출하도록 안내됩니다
• ["direct", "code_execution_20260120"] - Claude가 이 도구를 직접 또는 코드 실행 내에서 호출할 수 있습니다

"code_execution_20260120"과 "code_execution_20260521" 모두 allowed_callers에서 허용되며 서로 교환 가능합니다. 어느 코드 실행 도구 버전을 사용하는 요청이든 두 호출자 중 하나를 나열한 도구를 충족합니다. 응답 블록은 요청에서 선언한 버전과 관계없이 항상 호출자를 code_execution_20260120으로 태그합니다.

응답의 caller 필드

모든 도구 사용 블록에는 호출 방식을 나타내는 caller 필드가 포함됩니다:

직접 호출(기존 도구 사용):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

프로그래매틱 호출:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

tool_id는 호출을 수행한 코드 실행 server_tool_use 블록의 id이므로, 각 프로그래매틱 tool_use를 이를 생성한 코드 실행과 매칭할 수 있습니다.

컨테이너 수명 주기

프로그래매틱 도구 호출은 코드 실행과 동일한 컨테이너를 사용합니다:

• 컨테이너 생성: 기존 컨테이너를 재사용하지 않는 한 각 요청마다 새 컨테이너가 생성됩니다
• 컨테이너 ID: 응답의 container 필드에 expires_at 타임스탬프와 함께 반환됩니다
• 재사용: 상태를 유지하려면 다음 요청에 컨테이너 ID를 다시 전달하세요. 프로그래매틱 도구 호출이 결과를 기다리는 동안에는 해당 요청에서 컨테이너 ID가 선택 사항이 아니라 필수입니다. API는 컨테이너 ID가 없는 요청을 거부합니다.
• 만료: expires_at은 컨테이너의 남은 시간을 알려줍니다. 유휴 컨테이너는 현재 약 5분 후에 회수되며, 어떤 컨테이너도 생성 후 30일이 지나면 재사용할 수 없습니다.

예시 워크플로

전체 프로그래매틱 도구 호출 흐름은 다음과 같이 작동합니다:

1단계: 초기 요청

코드 실행과 프로그래매틱 호출을 허용하는 도구를 포함한 요청을 보냅니다. 프로그래매틱 호출을 활성화하려면 도구 정의에 allowed_callers 필드를 추가하세요.

요청 형태는 빠른 시작 예시와 동일합니다. 도구 목록에 code_execution을 포함하고, Claude가 코드에서 호출하기를 원하는 모든 도구에 allowed_callers: ["code_execution_20260120"]을 추가한 다음 사용자 메시지를 보내세요. 이 워크플로의 나머지 단계에서는 사용자 메시지 "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"를 사용합니다.

2단계: 도구 호출이 포함된 API 응답

Claude가 도구를 호출하는 코드를 작성합니다. API가 일시 중지되고 다음을 반환합니다:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

3단계: 도구 결과 제공

전체 대화 기록과 도구 결과를 함께 보냅니다. 이 요청에서는 세 가지 세부 사항이 중요합니다:

• 결과를 담는 사용자 메시지에는 tool_result 블록만 포함될 수 있습니다. 메시지 형식 제한을 참조하세요.
• 일시 중지된 응답의 container ID를 전달하세요. API는 대기 중인 프로그래매틱 도구 호출이 있지만 컨테이너 ID가 없는 연속 요청을 거부합니다.
• 원래 요청과 동일한 tools 배열을 보내세요. 일시 중지된 코드가 재개되려면 코드 실행 도구가 여전히 존재해야 하며, 이 요청에서 보내는 도구는 Claude와 실행 중인 코드가 턴의 나머지 동안 사용할 수 있는 정의입니다.

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll query the purchase history and analyze the results.",
                },
                {
                    "type": "server_tool_use",
                    "id": "srvtoolu_abc123",
                    "name": "code_execution",
                    "input": {"code": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    # 원래 요청과 동일한 tools 배열
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

4단계: 다음 도구 호출 또는 완료

코드는 일시 중지된 지점에서 다시 시작하여 결과를 처리합니다. 각 연속 응답은 더 많은 프로그래매틱 tool_use 블록과 함께 다시 일시 중지되거나, 코드 실행을 완료하고 Claude가 턴을 계속하도록 합니다(5단계). 둘을 구분하려면 stop_reason과 각 tool_use 블록의 caller를 확인하세요. 여러분을 위해 일시 중지된 응답은 stop_reason: "tool_use"와 caller가 코드 실행 버전을 지정하는 tool_use 블록을 가지며, 이 경우 하나의 사용자 메시지에 대기 중인 모든 프로그래매틱 호출에 대한 tool_result를 담아 3단계를 반복합니다.

5단계: 최종 응답

코드 실행이 완료되면 Claude가 최종 응답을 제공합니다:

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

고급 패턴

루프를 사용한 배치 처리

Claude는 여러 항목을 효율적으로 처리하는 코드를 작성할 수 있습니다:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# 프로그래밍 방식으로 결과 처리
top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

이 패턴은:

• 모델 왕복 횟수를 N(지역당 1회)에서 1로 줄입니다
• Claude에게 반환하기 전에 대규모 결과 집합을 프로그래매틱하게 처리합니다
• 원시 데이터 대신 집계된 결론만 반환하여 토큰을 절약합니다

조기 종료

Claude는 성공 기준이 충족되는 즉시 처리를 중단할 수 있습니다:

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health({"endpoint": endpoint})
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break  # Stop early, don't check remaining

조건부 도구 선택

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)

데이터 필터링

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)

응답 형식

프로그래매틱 도구 호출

코드 실행이 도구를 호출할 때:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

도구 결과 처리

도구 결과는 실행 중인 코드로 다시 전달됩니다:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

코드 실행 완료

모든 도구 호출이 충족되고 코드가 완료되면:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

오류 처리

일반적인 오류

도구 호출 중 컨테이너 만료

도구 결과가 약 4분 이내에 도착하지 않으면, 대기 중인 호출이 Claude의 실행 중인 코드 내부에서 TimeoutError를 발생시킵니다. Claude는 stderr에서 오류를 확인하고 일반적으로 호출을 재시도합니다:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

타임아웃을 방지하려면:

• 응답의 expires_at 필드를 모니터링하세요
• 도구 실행에 타임아웃을 구현하세요
• 긴 작업을 더 작은 단위로 나누는 것을 고려하세요

도구 실행 오류

도구가 오류를 반환하는 경우:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Claude의 코드는 이 오류를 받아 적절하게 처리할 수 있습니다.

제약 사항 및 제한

기능 비호환성

• 구조화된 출력: strict: true인 도구는 프로그래매틱 호출에서 지원되지 않습니다
• 도구 선택: tool_choice를 통해 특정 도구의 프로그래매틱 호출을 강제할 수 없습니다
• 병렬 도구 사용: disable_parallel_tool_use: true는 프로그래매틱 호출에서 지원되지 않습니다

입력 스키마 제한

input_schema에 재귀적 $ref(자기 자신을 참조하는 스키마와 같은 참조 순환)가 포함된 사용자 정의 도구는 프로그래매틱 호출을 활성화할 수 없습니다. 이러한 도구의 allowed_callers에 코드 실행 도구 버전을 포함하면 요청이 400 invalid_request_error로 실패하며, 메시지에 Circular $ref detected가 포함됩니다. 동일한 스키마는 직접 도구 호출에서는 허용됩니다.

이를 해결하려면 다음 중 하나를 수행하세요:

• allowed_callers를 생략하거나(["direct"]로 설정하여) 도구를 직접 호출 전용으로 유지하세요. 동일한 요청의 다른 도구는 여전히 프로그래매틱 호출을 사용할 수 있습니다.
• 스키마에서 순환을 제거하세요. 예를 들어, 재귀를 고정된 깊이로 펼치고 더 깊은 중첩은 가장 안쪽 수준의 description에 설명하거나, 재귀 속성을 예상 형태를 description에서 설명하는 일반 {"type": "object"}로 대체하세요.

도구 제한

다음 도구는 프로그래매틱하게 호출할 수 없습니다:

• MCP 커넥터가 제공하는 도구
• 컴퓨터 사용 및 브라우저 사용 도구 세트(computer_toolset_20260801 및 browser_toolset_20260801). 이들의 allowed_callers 필드는 "direct"만 허용합니다

메시지 형식 제한

프로그래매틱 도구 호출에 응답할 때는 엄격한 형식 요구 사항이 있습니다:

도구 결과만 포함된 응답: 결과를 기다리는 대기 중인 프로그래매틱 도구 호출이 있는 경우, 응답 메시지에는 오직 tool_result 블록만 포함되어야 합니다. 도구 결과 뒤에라도 텍스트 콘텐츠를 포함할 수 없습니다.

잘못된 예 - 프로그래매틱 도구 호출에 응답할 때 텍스트를 포함할 수 없습니다:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

올바른 예 - 프로그래매틱 도구 호출에 응답할 때는 도구 결과만 포함합니다:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

이 제한은 프로그래매틱(코드 실행) 도구 호출에 응답할 때만 적용됩니다. 일반 클라이언트 측 도구 호출의 경우 도구 결과 뒤에 텍스트 콘텐츠를 포함할 수 있습니다.

텍스트 전용 도구 결과 콘텐츠: 프로그래매틱 호출에 응답하는 각 tool_result의 content는 문자열 또는 text 블록이어야 합니다. 이미지, 문서 및 기타 콘텐츠 블록 유형은 거부됩니다.

속도 제한

프로그래매틱 도구 호출은 일반 도구 호출과 동일한 속도 제한이 적용됩니다. 코드 실행에서의 각 도구 호출은 별도의 호출로 계산됩니다.

사용 전 도구 결과 검증

프로그래매틱하게 호출될 사용자 정의 도구를 구현할 때:

• 도구 결과는 문자열로 반환됩니다: 실행 환경에서 처리될 수 있는 코드 스니펫이나 실행 가능한 명령을 포함하여 모든 콘텐츠를 담을 수 있습니다.
• 외부 도구 결과를 검증하세요: 도구가 외부 소스의 데이터를 반환하거나 사용자 입력을 받는 경우, 출력이 코드로 해석되거나 실행될 때의 코드 인젝션 위험에 유의하세요.

토큰 효율성

프로그래매틱 도구 호출은 세 가지 방식으로 토큰 소비를 줄입니다:

• 프로그래매틱 호출의 도구 결과는 Claude의 컨텍스트에 추가되지 않습니다 - 최종 코드 출력만 추가됩니다
• 중간 처리는 코드에서 이루어집니다 - 필터링, 집계 및 기타 변환은 모델 토큰을 소비하지 않습니다
• 하나의 코드 실행에서 여러 도구 호출 - 별도의 모델 턴에 비해 오버헤드가 줄어듭니다

예를 들어, 10개의 도구를 직접 호출하면 프로그래매틱하게 호출하고 요약을 반환하는 것보다 약 10배의 토큰을 사용합니다.

프로덕션 Claude 모델에 대한 Anthropic의 내부 평가에서:

• 75개 도구를 사용하는 프로젝트 관리 에이전트 벤치마크에서, 프로그래매틱 도구 호출을 활성화하면 작업 정확도 변화 없이 청구되는 입력 토큰이 약 38% 감소했습니다.
• 각 턴에서 한두 번의 순차적 도구 호출을 수행하는 τ²-bench(항공, 소매, 통신 도메인)에서는 프로그래매틱 도구 호출이 점수에 변화를 주지 않았고 비용은 약 8% 더 들었습니다. 순차적 단일 호출 워크플로는 이점을 얻지 못합니다.
• 프로덕션 API 트래픽 전반에서, tools 배열에 10~49개의 도구 정의가 포함된 요청은 프로그래매틱 도구 호출을 활성화했을 때 일반적으로 20%~40%의 토큰 절감을 보입니다.

실제 절감량은 워크로드 형태에 따라 다릅니다. 프로그래매틱 호출을 사용해야 하는 경우를 참조하세요.

사용량 및 가격

프로그래매틱 도구 호출은 코드 실행과 동일한 가격을 사용합니다. 자세한 내용은 코드 실행 가격을 참조하세요.

모범 사례

도구 설계

• 자세한 출력 설명을 제공하세요: Claude가 코드에서 도구 결과를 역직렬화하므로 형식(JSON 구조 및 필드 유형)을 문서화하세요
• 구조화된 데이터를 반환하세요: JSON 또는 기타 기계 판독 가능 형식이 프로그래매틱 처리에 가장 적합합니다
• 응답을 간결하게 유지하세요: 처리 오버헤드를 최소화하기 위해 필요한 데이터만 반환하세요

프로그래매틱 호출을 사용해야 하는 경우

프로그래매틱 도구 호출은 작은 고정 오버헤드(컨테이너 시작, 스크립트 생성)를 도구 결과 토큰과 모델 왕복에서의 큰 절감과 교환합니다. 이 교환이 이득이 되는지는 워크로드 형태에 따라 다릅니다.

적합한 경우:

• 많은 항목에 걸친 팬아웃 또는 병렬 작업(예: 50개 엔드포인트 확인 또는 20개 레코드 조회)
• Claude의 컨텍스트에 도달하기 전에 필터링, 집계 또는 요약할 수 있는 대용량 도구 결과
• 반복적인 쿼리와 결과 필터링이 워크플로를 지배하는 에이전트 검색 및 검색(retrieval)

적합하지 않은 경우:

• 각 호출이 이전 결과에 대한 Claude의 추론에 의존하는 엄격히 순차적인 워크플로. 이 경우 스크립트가 모델 왕복을 건너뛸 수 없기 때문입니다
• 응답이 작은 소수의 도구 호출, 특히 대화의 첫 번째 턴에서는 컨테이너 및 스크립트 오버헤드가 절감량을 초과할 수 있습니다
• 호출 사이에 즉각적인 사용자 피드백이 필요한 도구

확실하지 않다면, 광범위하게 활성화하기 전에 트래픽의 대표 샘플에서 allowed_callers를 사용한 경우와 사용하지 않은 경우의 청구 입력 토큰을 측정하세요.

성능 최적화

• 상태를 유지하기 위해 여러 관련 요청을 할 때 컨테이너를 재사용하세요
• 가능하면 단일 코드 실행에서 유사한 작업을 배치 처리하세요

문제 해결

일반적인 문제

tool_choice 설정 시 invalid_request_error

• tool_choice는 allowed_callers에 "direct"가 없는 도구를 지정할 수 없습니다. 해당 도구의 allowed_callers에 "direct"를 추가하거나, tool_choice에서 도구를 제거하고 Claude가 코드에서 호출하도록 하세요.

컨테이너 만료

• 일시 중지된 응답의 expires_at 타임스탬프보다 충분히 일찍 각 프로그래매틱 도구 호출에 응답하세요. Claude의 코드는 약 4분 후에 결과 대기를 중단하며, 유휴 컨테이너는 현재 약 5분 후에 회수됩니다.
• 더 빠른 도구 실행 구현을 고려하세요

도구 결과가 올바르게 파싱되지 않음

• 도구가 Claude가 역직렬화할 수 있는 문자열 데이터를 반환하는지 확인하세요
• 도구 설명에 명확한 출력 형식 문서를 제공하세요

디버깅 팁

1. 흐름을 추적하기 위해 모든 도구 호출과 결과를 로깅하세요
2. 프로그래매틱 호출을 확인하기 위해 caller 필드를 확인하세요
3. 적절한 재사용을 보장하기 위해 컨테이너 ID를 모니터링하세요
4. 프로그래매틱 호출을 활성화하기 전에 도구를 독립적으로 테스트하세요

프로그래매틱 도구 호출이 효과적인 이유

Claude는 대량의 코드로 학습되었으므로, 도구를 호출 가능한 Python 함수로 제시하면 그 강점을 활용할 수 있습니다:

• 도구 조합: 연쇄 호출, 루프, 조건문이 일련의 모델 왕복 대신 일반적인 Python 제어 흐름이 됩니다
• 결과 처리: Claude의 코드가 대용량 도구 출력을 필터링하고 집계하거나 파일에 기록하며, 최종 출력만 컨텍스트 윈도우에 들어갑니다
• 지연 시간: 하나의 코드 실행 내 도구 호출 사이에 모델이 다시 샘플링되지 않습니다

대안 구현

프로그래매틱 도구 호출은 자체 인프라에서도 구현할 수 있는 일반화 가능한 패턴입니다. 접근 방식을 비교하면 다음과 같습니다:

클라이언트 측 직접 실행

Claude에게 코드 실행 도구를 제공하고 해당 환경에서 사용 가능한 함수를 설명합니다. Claude가 코드로 도구를 호출하면 애플리케이션이 해당 함수가 정의된 로컬에서 이를 실행합니다.

장점:

• 애플리케이션 재설계가 최소화됩니다
• 환경과 지침에 대한 완전한 제어

단점:

• 샌드박스 외부에서 신뢰할 수 없는 코드를 실행합니다
• 도구 호출이 코드 인젝션의 경로가 될 수 있습니다

사용 시기: 애플리케이션이 임의의 코드를 안전하게 실행할 수 있고, 가장 작은 구현을 원하며, Anthropic의 관리형 제품이 요구 사항에 맞지 않는 경우.

자체 관리형 샌드박스 실행

Claude의 관점에서는 동일한 접근 방식이지만, 코드가 보안 제한(예: 네트워크 송신 차단)이 있는 샌드박스 컨테이너에서 실행됩니다. 도구에 외부 리소스가 필요한 경우 샌드박스 외부에서 도구 호출을 실행하기 위한 프로토콜이 필요합니다.

장점:

• 자체 인프라에서 안전한 프로그래매틱 도구 호출
• 실행 환경에 대한 완전한 제어

단점:

• 구축 및 유지 관리가 복잡합니다
• 인프라와 프로세스 간 통신을 모두 관리해야 합니다

사용 시기: 보안이 중요하고 Anthropic의 관리형 솔루션이 요구 사항에 맞지 않는 경우.

Anthropic 관리형 실행

Anthropic의 프로그래매틱 도구 호출은 Claude에 맞게 조정된 독자적인 Python 환경을 갖춘 샌드박스 실행의 관리형 버전입니다. Anthropic이 컨테이너 관리, 코드 실행 및 안전한 도구 호출 통신을 처리합니다.

장점:

• 기본적으로 안전하고 보안이 유지됩니다
• 실행할 인프라 없이 도구 정의만으로 활성화됩니다
• Claude에 최적화된 환경과 지침

Claude API, Claude Platform on AWS 또는 Microsoft Foundry를 사용하는 경우 Anthropic의 관리형 솔루션 사용을 고려하세요. Microsoft Foundry에서 프로그래매틱 도구 호출을 사용하려면 Hosted on Anthropic 배포가 필요합니다.

데이터 보존

프로그래매틱 도구 호출은 코드 실행 인프라를 기반으로 구축되었으며 동일한 샌드박스 컨테이너를 사용합니다. 실행 아티팩트 및 출력을 포함한 컨테이너 데이터는 최대 30일 동안 보존됩니다.

모든 기능에 대한 ZDR 적격성은 API 및 데이터 보존을 참조하세요.

다음 단계

Compatibility