Messages

工具呼叫

將模型提出的工具請求交由應用程式執行，再回傳結果以繼續對話。

POST /v1/messages

自訂函式由您的應用程式執行。模型提供函式名稱和參數，應用程式負責查詢資料並回傳結果。

請求與驗證

POST https://api.tokatlas.ai/v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

{
  "model": "claude-sonnet-4-6",
  "tools": [
    {
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "input_schema": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      }
    }
  ],
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Check stock for DEMO-001."
    }
  ]
}

工具呼叫格式

以下為呼叫項目示意；ID 與參數應取自實際回應。

{
  "type": "tool_use",
  "id": "toolu_example",
  "name": "lookup_stock",
  "input": {
    "sku": "DEMO-001"
  }
}

• 讀取 content 中所有 tool_use 區塊，保留完整 assistant 內容，並在緊接的 user 訊息中回傳對應的 tool_result；工具結果須放在使用者文字之前。

• tool_choice 可使用 {"type":"auto"}、{"type":"any"} 或 {"type":"tool","name":"lookup_stock"}。循環中使用自動選擇，讓模型可以結束呼叫。

• 串流時，依內容區塊索引合併 input_json_delta.partial_json，完整接收後再解析，勿執行尚未完整的參數。

多語言首輪請求

這組範例會取得模型的工具呼叫要求，尚未執行工具。讀取下方完整流程，以真實呼叫 ID 回傳工具結果並繼續對話。

執行方式見多語言範例說明。先設定 API_KEY，並替換模型、檔案網址及 ID 占位值；四種方式會顯示相同請求的原始回應。

cURL

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/messages" \
  --header "x-api-key: $API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "claude-sonnet-4-6",
  "tools": [
    {
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "input_schema": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      }
    }
  ],
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "Check stock for DEMO-001."
    }
  ],
  "max_tokens": 2048
}'

Python

import os
import requests

headers = {
    'x-api-key': os.environ["API_KEY"],
    'anthropic-version': '2023-06-01',
    'Content-Type': 'application/json',
}
payload = {'model': 'claude-sonnet-4-6',
 'tools': [{'name': 'lookup_stock',
            'description': 'Look up available inventory for a product SKU.',
            'input_schema': {'type': 'object',
                             'properties': {'sku': {'type': 'string',
                                                    'description': 'Product SKU, for '
                                                                   'example DEMO-001'}},
                             'required': ['sku'],
                             'additionalProperties': False}}],
 'stream': False,
 'messages': [{'role': 'user', 'content': 'Check stock for DEMO-001.'}],
 'max_tokens': 2048}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/messages', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)

JavaScript

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.API_KEY,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "claude-sonnet-4-6",
  "tools": [
    {
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "input_schema": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      }
    }
  ],
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": "Check stock for DEMO-001."
    }
  ],
  "max_tokens": 2048
}),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

Java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String payload = String.join("\n",
            "{",
            "  \"model\": \"claude-sonnet-4-6\",",
            "  \"tools\": [",
            "    {",
            "      \"name\": \"lookup_stock\",",
            "      \"description\": \"Look up available inventory for a product SKU.\",",
            "      \"input_schema\": {",
            "        \"type\": \"object\",",
            "        \"properties\": {",
            "          \"sku\": {",
            "            \"type\": \"string\",",
            "            \"description\": \"Product SKU, for example DEMO-001\"",
            "          }",
            "        },",
            "        \"required\": [",
            "          \"sku\"",
            "        ],",
            "        \"additionalProperties\": false",
            "      }",
            "    }",
            "  ],",
            "  \"stream\": false,",
            "  \"messages\": [",
            "    {",
            "      \"role\": \"user\",",
            "      \"content\": \"Check stock for DEMO-001.\"",
            "    }",
            "  ],",
            "  \"max_tokens\": 2048",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/messages"))
            .timeout(Duration.ofSeconds(180))
            .header("x-api-key", apiKey)
            .header("anthropic-version", "2023-06-01")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

完整 Python 範例

安裝 requests（pip install requests），並設定 API_KEY 環境變數。庫存結果為示範資料；請將 execute 替換為業務服務，並選用帳戶已開通的模型。

import json
import os
import requests

URL = "https://api.tokatlas.ai/v1/messages"
HEADERS = {'x-api-key': os.environ["API_KEY"], 'anthropic-version': '2023-06-01', 'Content-Type': 'application/json'}
TOOLS = [{'name': 'lookup_stock',
  'description': 'Look up available inventory for a product SKU.',
  'input_schema': {'type': 'object',
                   'properties': {'sku': {'type': 'string',
                                          'description': 'Product SKU, for example '
                                                         'DEMO-001'}},
                   'required': ['sku'],
                   'additionalProperties': False}}]


def post(payload):
    response = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
    response.raise_for_status()
    body = response.json()
    # Accept the documented gateway envelope or a direct protocol response.
    data = body.get("data", body)
    if not isinstance(data, dict):
        raise RuntimeError("Unexpected API response")
    if data.get("error"):
        raise RuntimeError(data["error"])
    return data


def execute(name, args):
    if name != "lookup_stock":
        return {"error": "Unknown tool"}
    if not isinstance(args, dict) or set(args) != {"sku"}:
        return {"error": "Expected exactly one sku argument"}
    if not isinstance(args["sku"], str) or not args["sku"].strip():
        return {"error": "sku must be a non-empty string"}
    # Demo fixture only; replace with your inventory service.
    stock = {"DEMO-001": 18}
    if args["sku"] not in stock:
        return {"error": "SKU not found"}
    return {"sku": args["sku"], "available": stock[args["sku"]]}

messages = [{"role": "user", "content": "Check stock for DEMO-001."}]
for _ in range(6):
    reply = post({"model": "claude-sonnet-4-6", "max_tokens": 2048,
                  "tools": TOOLS, "messages": messages})
    if reply.get("stop_reason") == "max_tokens":
        raise RuntimeError("Truncated response; increase max_tokens")
    blocks = reply["content"]
    calls = [b for b in blocks if b["type"] == "tool_use"]
    if not calls:
        print("\n".join(b["text"] for b in blocks if b["type"] == "text"))
        break
    messages.append({"role": "assistant", "content": blocks})
    results = []
    for call in calls:
        result = execute(call["name"], call["input"])
        results.append({"type": "tool_result", "tool_use_id": call["id"],
                        "content": json.dumps(result), "is_error": "error" in result})
    messages.append({"role": "user", "content": results})
else:
    raise RuntimeError("Tool round limit reached")

常見問題

狀況	檢查方式
缺少工具結果	每個呼叫都須回傳結果，保留原始 ID。
重複呼叫	避免每輪強制使用工具，並限制循環次數。
參數無效	執行前驗證函式名稱與參數。
工具執行失敗	回傳結構化錯誤，勿編造資料。
選項不支援	檢查模型與閘道路由的能力。

相關主題

• 概覽
• 檔案分析
• Claude tool use