Programmatic Tool Calling (PTC) — Giảm latency, tăng hiệu suất

Trong tool use truyền thống, mỗi lần Claude muốn gọi một tool, phải có một "round-trip": Claude → API → tool → API → Claude. Với 100 records cần xử lý, đó là 100 round-trips. Với Programmatic Tool Calling (PTC), Claude viết code xử lý toàn bộ logic trong Code Execution environment — từ 100 round-trips xuống còn 1.

Vấn đề với traditional tool calling

Hãy xem xét bài toán: phân tích expense reports của toàn bộ team tháng 12, mỗi nhân viên có 100+ khoản chi.

Traditional approach: Sequential round-trips

# Traditional tool calling — mỗi call là một round-trip
# Với 5 nhân viên x 100 records = 500 round-trips qua API

Luong: Claude call get_expenses("nguyen_van_a")
       → API round-trip 1
       Claude call get_expenses("nguyen_van_b")
       → API round-trip 2
       ... (500 times total)
       Claude: "Tong chi tieu: X"

# Latency: 500 x 200ms = 100 giay
# Tokens: 500 tool call definitions x lặp lại mỗi lần

Đây không phải vấn đề nhỏ. Với real-world workloads — inventory systems, analytics pipelines, batch processing — traditional tool calling tạo ra bottleneck nghiêm trọng về cả latency lẫn cost.

Programmatic Tool Calling: Claude viết code thay vì gọi từng tool

Với PTC, Claude có thể viết Python code chạy trong Code Execution environment, trong đó code đó gọi tools trực tiếp. Toàn bộ processing xảy ra trong một "execution step" thay vì hàng trăm round-trips.

# PTC approach — Claude viết code xử lý toàn bộ
# 1 round-trip duy nhất cho code execution

Claude viết:
  employees = ["nguyen_van_a", "nguyen_van_b", ...]
  all_expenses = []
  for emp in employees:
      data = get_expenses(emp)  # tool call trong code
      all_expenses.extend(data)

  total = sum(e["amount"] for e in all_expenses)
  by_category = {}
  for e in all_expenses:
      cat = e["category"]
      by_category[cat] = by_category.get(cat, 0) + e["amount"]

  print(f"Total: {total:,.0f} VND")
  print("By category:", by_category)

# Latency: 1 execution step ~ 2-5 giay
# Tokens: tool definition chi xuat hien 1 lan

Setup: Beta API và allowed_callers

PTC yêu cầu beta messages API và cấu hình allowed_callers để chỉ định code execution được phép gọi tools nào:

import anthropic
import json

client = anthropic.Anthropic()

# Define tools với allowed_callers
# allowed_callers: ["code_execution"] cho phép code gọi tool này
EXPENSE_TOOLS = [
    {
        "name": "get_employee_expenses",
        "description": "Lay tat ca expense records cua mot nhan vien trong thang",
        "input_schema": {
            "type": "object",
            "properties": {
                "employee_id": {
                    "type": "string",
                    "description": "ID nhan vien"
                },
                "month": {
                    "type": "string",
                    "description": "Thang dang ky, format: YYYY-MM"
                }
            },
            "required": ["employee_id", "month"]
        },
        # PTC key: cho phep code execution goi tool nay
        "allowed_callers": ["code_execution"]
    },
    {
        "name": "get_expense_policy",
        "description": "Lay chinh sach chi tieu cua cong ty",
        "input_schema": {
            "type": "object",
            "properties": {
                "category": {"type": "string"}
            },
            "required": ["category"]
        },
        "allowed_callers": ["code_execution"]
    },
    {
        "name": "flag_expense_violation",
        "description": "Danh dau mot expense vi pham chinh sach",
        "input_schema": {
            "type": "object",
            "properties": {
                "expense_id": {"type": "string"},
                "reason": {"type": "string"},
                "amount_over_limit": {"type": "number"}
            },
            "required": ["expense_id", "reason"]
        },
        "allowed_callers": ["code_execution"]
    }
]

Mock data cho demo

import random

def generate_mock_expenses(employee_id, month):
    """Tao du lieu expense gia."""
    categories = ["travel", "meals", "software", "office", "training"]
    limits = {
        "travel": 5000000,    # 5M VND
        "meals": 500000,       # 500K VND/lan
        "software": 2000000,  # 2M VND
        "office": 300000,
        "training": 3000000
    }

    expenses = []
    random.seed(hash(employee_id + month))

    for i in range(random.randint(80, 120)):
        cat = random.choice(categories)
        limit = limits[cat]
        # 10% chance vi pham
        amount = random.randint(
            int(limit * 0.3),
            int(limit * 1.4 if random.random() < 0.1 else limit * 0.9)
        )
        expenses.append({
            "id": f"EXP-{employee_id}-{i:03d}",
            "employee_id": employee_id,
            "category": cat,
            "amount": amount,
            "date": f"{month}-{random.randint(1,28):02d}",
            "description": f"Chi tieu {cat} ngay {i+1}",
            "limit": limit
        })

    return expenses

# Simulate tool execution
def execute_tool(tool_name, tool_input):
    if tool_name == "get_employee_expenses":
        return generate_mock_expenses(
            tool_input["employee_id"],
            tool_input["month"]
        )

    elif tool_name == "get_expense_policy":
        policies = {
            "travel": {"limit": 5000000, "requires_receipt": True, "approval": "manager"},
            "meals": {"limit": 500000, "requires_receipt": False, "approval": "none"},
            "software": {"limit": 2000000, "requires_receipt": True, "approval": "it_dept"},
            "office": {"limit": 300000, "requires_receipt": False, "approval": "none"},
            "training": {"limit": 3000000, "requires_receipt": True, "approval": "hr"}
        }
        return policies.get(tool_input["category"], {"error": "Unknown category"})

    elif tool_name == "flag_expense_violation":
        print(f"[FLAG] Expense {tool_input['expense_id']}: {tool_input['reason']}")
        return {"flagged": True, "ticket_id": f"VIOL-{tool_input['expense_id']}"}

Chạy PTC Agent

def run_ptc_expense_analysis():
    employees = [
        "nguyen_van_a", "tran_thi_b", "le_van_c",
        "pham_thi_d", "hoang_van_e"
    ]

    user_prompt = f"""Phan tich expense reports thang 12/2024 cho cac nhan vien sau: {employees}

    Hay viet Python code de:
    1. Lay tat ca expenses cua tung nhan vien (dung get_employee_expenses)
    2. Kiem tra tung khoan chi voi policy (dung get_expense_policy)
    3. Flag cac violation (dung flag_expense_violation)
    4. Tao bao cao tong ket: tong chi tieu theo nhan vien, theo category, so violation

    Xu ly tat ca records bang code, khong goi tool tung cai mot."""

    messages = [{"role": "user", "content": user_prompt}]

    print("Starting PTC expense analysis...")
    import time
    start = time.time()

    while True:
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=8192,
            tools=EXPENSE_TOOLS,
            messages=messages,
            # Enable beta API cho PTC
            extra_headers={
                "anthropic-beta": "interleaved-thinking-2025-05-14"
            }
        )

        if response.stop_reason == "end_turn":
            elapsed = time.time() - start
            print(f"
Completed in {elapsed:.1f}s")
            for block in response.content:
                if hasattr(block, 'text'):
                    print(block.text)
            break

        elif response.stop_reason == "tool_use":
            messages.append({"role": "assistant", "content": response.content})
            tool_results = []

            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    records = len(result) if isinstance(result, list) else 1
                    print(f"[Tool] {block.name} returned {records} records")
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": json.dumps(result)
                    })

            messages.append({"role": "user", "content": tool_results})
        else:
            break

run_ptc_expense_analysis()

Stateful workflows với container_id

Một tính năng mạnh của PTC: container_id cho phép nhiều requests chia sẻ cùng một execution environment. Biến, kết quả tính toán, datasets được persist giữa các calls:

# Request 1: Load và preprocess data
response1 = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    tools=EXPENSE_TOOLS,
    messages=[{
        "role": "user",
        "content": "Load expense data cho Q4 2024 va tinh toan statistics co ban"
    }],
    extra_body={
        "container_id": "expense-analysis-q4-2024"  # stateful container
    }
)

# Request 2: Cung container, data tu request 1 van con
response2 = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    tools=EXPENSE_TOOLS,
    messages=[{
        "role": "user",
        "content": "Dung data da load, tim cac outliers va vi pham nghiem trong nhat"
    }],
    extra_body={
        "container_id": "expense-analysis-q4-2024"  # same container
    }
)

# Request 3: Generate final report tu ket qua da co
response3 = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    tools=EXPENSE_TOOLS,
    messages=[{
        "role": "user",
        "content": "Tao bao cao PDF-ready tu tat ca analysis tren"
    }],
    extra_body={
        "container_id": "expense-analysis-q4-2024"
    }
)

So sánh hiệu suất

Khi nào nên dùng PTC?

Ideal use cases:

• Batch processing — Xử lý 50+ records trong một session
• Data analysis pipelines — Aggregate, filter, transform large datasets
• Report generation — Thu thập data từ nhiều sources, tổng hợp
• Inventory management — Check stock levels, update pricing cho toàn bộ catalog
• Scheduled jobs — Nightly reconciliation, monthly reports

Không phù hợp khi:

• Tool calls cần human-in-the-loop approval từng bước
• Real-time streaming responses quan trọng
• Tool calls có side effects nguy hiểm cần review thủ công

Tổng kết

Programmatic Tool Calling là bước tiến lớn trong hiệu suất của Claude agents:

• Giảm latency 10-20x bằng cách loại bỏ round-trips không cần thiết
• Giảm token usage 60-80% vì tool definitions không lặp lại mỗi turn
• Xử lý large datasets với full Python power trong Code Execution
• Stateful workflows qua container_id cho multi-step analysis

Bước tiếp theo: Tìm hiểu Tool Use với Pydantic để thêm type safety và validation cho tool responses — đặc biệt quan trọng khi xử lý large batches như trong PTC.