Tool use

{
  "tools": [{
    "name": "get_order",
    "description": "Look up an order by ID. Call this whenever the user asks about an order's status, contents or delivery.",
    "input_schema": {
      "type": "object",
      "properties": {"order_id": {"type": "string", "description": "Order ID, e.g. A-1042"}},
      "required": ["order_id"]
    }
  }],
  "messages": [{"role": "user", "content": "Where is my order A-1042?"}]
}

{
  "stop_reason": "tool_use",
  "content": [
    {"type": "text", "text": "Let me look that up."},
    {"type": "tool_use", "id": "toolu_01A", "name": "get_order", "input": {"order_id": "A-1042"}}
  ]
}

{
  "messages": [
    {"role": "user", "content": "Where is my order A-1042?"},
    {"role": "assistant", "content": [
      {"type": "text", "text": "Let me look that up."},
      {"type": "tool_use", "id": "toolu_01A", "name": "get_order", "input": {"order_id": "A-1042"}}
    ]},
    {"role": "user", "content": [
      {"type": "tool_result", "tool_use_id": "toolu_01A", "content": "{\"status\": \"shipped\", \"eta\": \"2026-10-14\"}"}
    ]}
  ]
}

from anthropic.types import ToolParam

TOOLS: list[ToolParam] = [
    {
        "name": "get_order",
        "description": (
            "Look up a customer's order by its ID and return its status, items, total and delivery date. "
            "Call this whenever the user asks about an order's status, contents, delivery or refund eligibility. "
            "Returns an error if the order doesn't exist."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string", "description": "Order ID as the customer wrote it, e.g. A-1042"},
            },
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
    {
        "name": "refund_order",
        "description": (
            "Refund an order in full. Only call this after get_order shows the order was delivered "
            "within the last 30 days, and only when the customer has explicitly asked for a refund."
        ),
        "strict": True,
        "input_schema": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
                "reason": {"type": "string", "enum": ["damaged", "wrong_item", "not_as_described", "other"]},
            },
            "required": ["order_id", "reason"],
            "additionalProperties": False,
        },
    },
]

import json

import anthropic
from anthropic.types import MessageParam, ToolResultBlockParam

client = anthropic.Anthropic()
MODEL = "claude-sonnet-5-5"
SYSTEM = "You are a support assistant for an online shop. Use the tools to answer; never guess order details."

ORDERS = {
    "A-1042": {"status": "delivered", "delivered": "2026-10-02", "items": ["Desk lamp"], "total": "$49.00"},
    "A-1043": {"status": "shipped", "eta": "2026-10-14", "items": ["Bookshelf"], "total": "$189.00"},
}

class ToolError(Exception):
    """A failure the model should see and can recover from."""

def get_order(order_id: str) -> dict:
    if order_id not in ORDERS:
        raise ToolError(f"Order {order_id} not found. Ask the customer to check the ID.")
    return ORDERS[order_id]

def refund_order(order_id: str, reason: str) -> dict:
    order = get_order(order_id)
    if order["status"] != "delivered":
        raise ToolError(f"Order {order_id} is {order['status']}, not delivered, so it can't be refunded yet.")
    answer = input(f"\n[approval] Refund {order_id} ({order['total']}) for '{reason}'? [y/N] ")
    if answer.strip().lower() != "y":
        raise ToolError("A staff member declined this refund. Tell the customer a human will follow up.")
    return {"refunded": True, "amount": order["total"]}

HANDLERS = {"get_order": get_order, "refund_order": refund_order}

def run_tool(name: str, args: dict) -> str:
    handler = HANDLERS.get(name)
    if handler is None:
        raise ToolError(f"Unknown tool {name}")
    return json.dumps(handler(**args))

def run_conversation(user_text: str, max_rounds: int = 8) -> str:
    messages: list[MessageParam] = [{"role": "user", "content": user_text}]
    for _ in range(max_rounds):
        response = client.messages.create(
            model=MODEL, max_tokens=4096, system=SYSTEM, tools=TOOLS, messages=messages,
        )
        match response.stop_reason:
            case "end_turn":
                return "".join(b.text for b in response.content if b.type == "text")
            case "refusal":
                return "Sorry, I can't help with that."
            case "max_tokens":
                raise RuntimeError("Response truncated; never run a tool call that may be cut off")
            case "tool_use":
                pass
            case other:
                raise RuntimeError(f"Unexpected stop_reason: {other}")

        messages.append({"role": "assistant", "content": response.content})
        results: list[ToolResultBlockParam] = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            print(f"  -> {block.name}({block.input})")
            try:
                output = run_tool(block.name, block.input)
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": output})
            except ToolError as e:
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(e), "is_error": True})
        messages.append({"role": "user", "content": results})

    raise RuntimeError(f"No final answer after {max_rounds} tool rounds")

print(run_conversation("My lamp from order A-1042 arrived broken. Can I get my money back?"))

  -> get_order({'order_id': 'A-1042'})
  -> refund_order({'order_id': 'A-1042', 'reason': 'damaged'})

[approval] Refund A-1042 ($49.00) for 'damaged'? [y/N] y
I'm sorry the lamp arrived broken. I've refunded order A-1042 in full ($49.00).
You should see the money back on your original payment method within a few days.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function runConversation(
  userText: string,
  tools: Anthropic.Tool[],
  runTool: (name: string, input: unknown) => Promise<string>,
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: userText }];
  for (let round = 0; round < 8; round++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5-5",
      max_tokens: 4096,
      tools,
      messages,
    });
    if (response.stop_reason === "end_turn") {
      return response.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
    }
    if (response.stop_reason === "refusal") return "Sorry, I can't help with that.";
    if (response.stop_reason !== "tool_use") throw new Error(`Unexpected stop_reason: ${response.stop_reason}`);

    messages.push({ role: "assistant", content: response.content });
    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type !== "tool_use") continue;
      try {
        results.push({ type: "tool_result", tool_use_id: block.id, content: await runTool(block.name, block.input) });
      } catch (err) {
        results.push({ type: "tool_result", tool_use_id: block.id, content: String(err), is_error: true });
      }
    }
    messages.push({ role: "user", content: results });
  }
  throw new Error("No final answer after 8 tool rounds");
}