Agent & tool foundations

tool_schemas.pyimport json

# A tool schema tells the model the tool's name, what it's for, and its parameters.
CALCULATOR = {
    'name': 'calculator',
    'description': 'Evaluate a basic arithmetic expression like "2 + 3 * 4".',
    'parameters': {
        'type': 'object',
        'properties': {
            'expression': {'type': 'string', 'description': 'The arithmetic to evaluate.'},
        },
        'required': ['expression'],
    },
}

GET_WEATHER = {
    'name': 'get_weather',
    'description': 'Get the current weather for a city.',
    'parameters': {
        'type': 'object',
        'properties': {
            'city': {'type': 'string', 'description': 'City name, e.g. "Paris".'},
            'unit': {'type': 'string', 'enum': ['c', 'f'], 'description': 'Temperature unit.'},
        },
        'required': ['city'],
    },
}

print(json.dumps(CALCULATOR, indent=2))
print('tools advertised:', [CALCULATOR['name'], GET_WEATHER['name']])

tiny_agent.py# ---- 1. the tool: a real Python function ----
def calculator(expression):
    # A safe tiny evaluator for + - * / on numbers (no names, no calls).
    return eval(expression, {'__builtins__': {}}, {})

TOOLS = {'calculator': calculator}

# ---- 2. a FAKE model. A real LLM drops into exactly this slot. ----
# It reads the conversation and returns either a tool call or a final answer.
def fake_model(messages):
    last = messages[-1]
    if last['role'] == 'user':
        # First look at the question -> decide to use the calculator.
        return {'type': 'tool_call', 'name': 'calculator',
                'args': {'expression': '2 + 3 * 4'}}
    # We just saw a tool result -> now answer for real.
    return {'type': 'final', 'text': f"The answer is {last['content']}."}

# ---- 3. the agent loop (this part never changes when you swap in a real model) ----
def run_agent(question, max_steps=5):
    messages = [{'role': 'user', 'content': question}]
    for step in range(max_steps):
        decision = fake_model(messages)
        if decision['type'] == 'final':
            return decision['text'], messages
        # The model proposed a tool call: run it and feed the result back.
        name, args = decision['name'], decision['args']
        result = TOOLS[name](**args)
        messages.append({'role': 'assistant', 'content': f'call {name}({args})'})
        messages.append({'role': 'tool', 'content': result})
    return 'stopped: too many steps', messages

answer, transcript = run_agent('what is 2 + 3 * 4?')
print('TRANSCRIPT:')
for m in transcript:
    print(f"  {m['role']:9} | {m['content']}")
print('\nFINAL:', answer)

dispatch.pydef calculator(expression):
    return eval(expression, {'__builtins__': {}}, {})

def get_weather(city, unit='c'):
    # A stub — a real version would call a weather API here.
    return f'18 degrees {unit} and clear in {city}'

TOOLS = {'calculator': calculator, 'get_weather': get_weather}

def dispatch(name, args):
    fn = TOOLS.get(name)
    if fn is None:
        # Return an error string instead of raising — the model can read it and recover.
        return f"error: no tool named '{name}'. available: {sorted(TOOLS)}"
    try:
        return fn(**args)
    except Exception as e:
        return f'error running {name}: {e}'

print(dispatch('calculator', {'expression': '10 / 4'}))
print(dispatch('get_weather', {'city': 'Paris', 'unit': 'f'}))
print(dispatch('teleport', {'to': 'Mars'}))          # unknown tool
print(dispatch('calculator', {'expression': '1/0'}))  # tool raises

real_tool_use.py# The real agent loop. Complete and correct; needs YOUR API key to actually run.
# pip install anthropic ; export ANTHROPIC_API_KEY=sk-...
from anthropic import Anthropic          # runs in your own environment, not the sandbox

client = Anthropic()

def calculator(expression):
    return eval(expression, {'__builtins__': {}}, {})
TOOLS = {'calculator': calculator}

# Same tool schema as section 2, in the shape the API expects (input_schema).
tools = [{
    'name': 'calculator',
    'description': 'Evaluate a basic arithmetic expression like "2 + 3 * 4".',
    'input_schema': {
        'type': 'object',
        'properties': {'expression': {'type': 'string'}},
        'required': ['expression'],
    },
}]

messages = [{'role': 'user', 'content': 'what is 2 + 3 * 4?'}]
while True:
    resp = client.messages.create(
        model='claude-opus-4-8', max_tokens=1024, tools=tools, messages=messages,
    )
    if resp.stop_reason != 'tool_use':
        # The model gave a final answer -> print the text and stop the loop.
        print(next(b.text for b in resp.content if b.type == 'text'))
        break
    # The model asked for a tool. Run each requested tool and feed results back.
    messages.append({'role': 'assistant', 'content': resp.content})
    results = []
    for block in resp.content:
        if block.type == 'tool_use':                 # block.name / .input / .id
            output = TOOLS[block.name](**block.input)
            results.append({'type': 'tool_result', 'tool_use_id': block.id,
                            'content': str(output)})
    messages.append({'role': 'user', 'content': results})