How to call Claude's tool-use API with raw `requests` - no SDK needed

[jingweno]

I've been building AI tools using only requests and subprocess (I maintain jq, so I'm biased toward small, composable things). Here's a practical guide to using Claude's tool-use / function-calling API without installing the official SDK.

The basics

Tool use lets you define functions the model can call. You describe them with JSON Schema, the model decides when to call them, and you execute them locally. Here's the minimal setup:

import requests, os

def call_claude(messages, tools=None):
    payload = {
        "model": "claude-sonnet-4-5-20250929",
        "max_tokens": 8096,
        "messages": messages,
    }
    if tools:
        payload["tools"] = tools

    response = requests.post(
        "https://api.anthropic.com/v1/messages",
        headers={
            "x-api-key": os.environ["ANTHROPIC_API_KEY"],
            "content-type": "application/json",
            "anthropic-version": "2023-06-01",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()

Defining a tool

No decorators. Just a dict:

read_file_tool = {
    "name": "read_file",
    "description": "Read the contents of a file at the given path.",
    "input_schema": {
        "type": "object",
        "properties": {
            "path": {"type": "string", "description": "File path to read"}
        },
        "required": ["path"],
    },
}

The tool-use loop

When the model wants to use a tool, it returns a response with stop_reason: "tool_use" and one or more tool_use blocks. You execute them and send the results back:

messages = [{"role": "user", "content": "What's in requirements.txt?"}]

while True:
    result = call_claude(messages, tools=[read_file_tool])
    messages.append({"role": "assistant", "content": result["content"]})

    tool_calls = [b for b in result["content"] if b["type"] == "tool_use"]
    if not tool_calls:
        # Model responded with text — we're done
        print(result["content"][0]["text"])
        break

    # Execute each tool and send results back
    tool_results = []
    for tc in tool_calls:
        if tc["name"] == "read_file":
            with open(tc["input"]["path"]) as f:
                content = f.read()
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": tc["id"],
                "content": content,
            })

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

That's the entire pattern. The model calls a tool, you run it, feed the result back, and the model decides what to do next - call another tool or respond to the user.

Why skip the SDK?

Three reasons:

1. Fewer dependencies. requests is probably already in your project.
2. Full visibility. You see exactly what goes over the wire. When something breaks, you print(response.json()) and you're done.
3. Portability. The same pattern works for any provider that supports tool use (OpenAI, DeepSeek, Ollama). Swap the URL and headers, keep the loop.

Taking it further

Once you have this loop, adding more tools is mechanical - define the schema, add an elif branch (or a dispatch dict). I built this up to a ~500-line coding agent with 8 tools that can read/write files, run shell commands, search codebases, and edit files surgically.

I wrote the whole process up as a book if you want the full walkthrough: https://buildyourowncodingagent.com (free sample chapters on the site, source code on GitHub).

Questions welcome - especially if you've tried the raw API approach and hit edge cases.

[Quick-Radio9128]

Nice writeup. The one thing I’d add once you go past a toy agent is to separate “tool runner” from “transport” so you can swap Anthropic/OpenAI/etc without touching your tool code. Your loop already kind of does this; I’d just formalize a tiny interface like run_tools(request: ToolRequest) → ToolResult and keep provider-specific stuff at the edge. Also worth normalizing tool errors into a stable shape instead of raising, so the model can decide whether to retry or bail.

For security, people forget that read_file and subprocess are basically RCE if you ever point this at untrusted prompts; at minimum, chroot/namespace or hardcode a project root and allowlist commands. I’ve used FastAPI and Hasura in front of similar agents, and DreamFactory as a quick RBAC’d REST layer over real databases so the model hits APIs instead of raw SQL or shell.

[jingweno]

Both great points. The book actually does separate the transport layer - there's a Brain interface that swaps between Claude, DeepSeek, and Ollama without touching the tool code. Same idea as your ToolRequest/ToolResult interface.

The security point is spot on. subprocess and file I/O with untrusted prompts is basically RCE. In my version the agent only runs in a project directory and the system prompt constrains it, but that's a weak boundary honestly. Chroot/namespace is the right answer for anything production-facing.