Structured Outputs & Tool Use

# extract_freeform.py - asking nicely and hoping for structure

import anthropic

client = anthropic.Anthropic()

TICKET = (
    "Hi, this is Dana Reyes (dana.reyes@northwind.example). Our checkout page "
    "has been throwing 500s since this morning and we're losing sales. "
    "We're on the Enterprise plan. Please escalate."
)

response = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=300,
    messages=[{
        "role": "user",
        "content": f"Extract the customer details from this ticket:\n\n{TICKET}",
    }],
)
print(next(b.text for b in response.content if b.type == "text"))

# extract_parse.py - the same request, constrained by a Pydantic model

import anthropic
from pydantic import BaseModel

client = anthropic.Anthropic()

TICKET = (
    "Hi, this is Dana Reyes (dana.reyes@northwind.example). Our checkout page "
    "has been throwing 500s since this morning and we're losing sales. "
    "We're on the Enterprise plan. Please escalate."
)


class Ticket(BaseModel):
    customer_name: str
    email: str
    plan: str
    severity: str
    summary: str
    tags: list[str]


response = client.messages.parse(
    model="claude-haiku-4-5",
    max_tokens=500,
    messages=[{"role": "user", "content": f"Extract the ticket details:\n\n{TICKET}"}],
    output_format=Ticket,
)

ticket = response.parsed_output          # a validated Ticket instance
print(type(ticket).__name__)
print(ticket.customer_name)
print(ticket.email)
print(ticket.plan)
print(ticket.severity)
print(ticket.tags)

# the JSON Schema Pydantic sends on your behalf

import json

print(json.dumps(Ticket.model_json_schema(), indent=2))

# tool_loop.py - the hand-written loop, driven by stop_reason

import json

FAKE = {"Madrid": 34, "Oslo": 12, "Cairo": 41}


def get_weather(city: str, unit: str) -> str:
    if city not in FAKE:
        raise KeyError(f"no station for {city}")
    c = FAKE[city]
    return f"{c}C" if unit == "celsius" else f"{round(c * 9 / 5 + 32)}F"


messages = [{"role": "user", "content": "What's the weather in Madrid in celsius?"}]
turn = 0

while True:
    turn += 1
    resp = client.messages.create(
        model="claude-haiku-4-5", max_tokens=512, tools=TOOLS, messages=messages,
    )
    print(f"turn {turn}: stop_reason = {resp.stop_reason}")

    # Anything other than tool_use means Claude is done talking to your code.
    if resp.stop_reason != "tool_use":
        break

    # Append the WHOLE assistant message, tool_use blocks included.
    messages.append({"role": "assistant", "content": resp.content})

    results = []
    for block in resp.content:
        if block.type == "tool_use":
            print(f"         tool  = {block.name}({json.dumps(block.input)})")
            out = get_weather(**block.input)
            print(f"         result= {out}")
            results.append({
                "type": "tool_result",
                "tool_use_id": block.id,   # must match the tool_use block
                "content": out,
            })

    # All results go back in ONE user message.
    messages.append({"role": "user", "content": results})

print("final  :", next(b.text for b in resp.content if b.type == "text"))

# tool_runner.py - the same loop, driven by the SDK

from anthropic import beta_tool

@beta_tool
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get the current weather for a city.

    Args:
        city: City name, e.g. Madrid.
        unit: Either "celsius" or "fahrenheit".
    """
    return f"{FAKE[city]}{'C' if unit == 'celsius' else 'F'}"


runner = client.beta.messages.tool_runner(
    model="claude-haiku-4-5",
    max_tokens=512,
    tools=[get_weather],
    messages=[{"role": "user", "content": "Weather in Madrid?"}],
)

for message in runner:      # the loop above, handled for you
    print(message.stop_reason)

# parallel_calls.py - three tool_use blocks in one assistant message

messages = [{
    "role": "user",
    "content": "Compare the weather in Madrid, Oslo and Cairo in celsius.",
}]

resp = client.messages.create(
    model="claude-haiku-4-5", max_tokens=800, tools=TOOLS, messages=messages,
)

calls = [b for b in resp.content if b.type == "tool_use"]
print(f"tool_use blocks in ONE assistant message: {len(calls)}")
for b in calls:
    print("   ->", b.name, json.dumps(b.input))

# Execute them (concurrently, in real code), then return EVERY result
# in a single user message. Splitting them across messages teaches the
# model to stop asking for parallel calls.
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": b.id, "content": get_weather(**b.input)}
    for b in calls
]})

# tool_error.py - reporting failure with is_error instead of dropping it

messages = [{"role": "user", "content": "What's the weather in Lisbon in celsius?"}]
resp = client.messages.create(
    model="claude-haiku-4-5", max_tokens=512, tools=TOOLS, messages=messages,
)

block = next(b for b in resp.content if b.type == "tool_use")
try:
    out, err = get_weather(**block.input), False
except KeyError as exc:
    out, err = f"Error: {exc}", True      # Lisbon is not in FAKE

messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [{
    "type": "tool_result",
    "tool_use_id": block.id,
    "content": out,
    "is_error": err,        # tell the model it failed, do not drop the result
}]})

resp = client.messages.create(
    model="claude-haiku-4-5", max_tokens=512, tools=TOOLS, messages=messages,
)
print(next(b.text for b in resp.content if b.type == "text"))