Anthropic Tool Calling

This guide shows how to integrate Seltz as a search tool for Claude models. When Claude needs to search for information, it will call your Seltz-powered function and use the results to generate informed responses.

Prerequisites

Anthropic API key (Get one here)
Seltz API key (Get one here)

Installation

pip install anthropic seltz

Setup

Set your API keys as environment variables:

export ANTHROPIC_API_KEY="your-anthropic-key"
export SELTZ_API_KEY="your-seltz-key"

Initialize both clients:

from anthropic import Anthropic
from seltz import Seltz

anthropic_client = Anthropic()
seltz_client = Seltz()

Define the Search Tool

Create a tool schema that describes the Seltz search function to Claude:

tools = [
    {
        "name": "search",
        "description": "Search for information on the web. Use this tool when you need current information or facts you don't know. Returns relevant documents with URLs and content.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of results to return (default: 5)"
                }
            },
            "required": ["query"]
        }
    }
]

Using the Messages API

Here’s a complete example using Anthropic’s Messages API with Seltz search:

import json
from anthropic import Anthropic
from seltz import Seltz

# Initialize clients
anthropic_client = Anthropic()
seltz_client = Seltz()

# Define the search tool
tools = [
    {
        "name": "search",
        "description": "Search for information on the web. Use this tool when you need current information or facts you don't know. Returns relevant documents with URLs and content.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum number of results to return (default: 5)"
                }
            },
            "required": ["query"]
        }
    }
]


def search(query: str, max_results: int = 5) -> str:
    """Execute a Seltz search and return results as JSON."""
    response = seltz_client.search(query, max_results=max_results)
    results = [
        {"url": doc.url, "content": doc.content}
        for doc in response.documents
    ]
    return json.dumps(results)


def chat(user_message: str) -> str:
    """Send a message and handle tool calls."""
    messages = [{"role": "user", "content": user_message}]

    # Initial request
    response = anthropic_client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        messages=messages,
        tools=tools
    )

    # Check if Claude wants to use a tool
    if response.stop_reason == "tool_use":
        # Claude may ask for several tools in one turn, and every tool_use
        # block needs its own tool_result in the next message.
        tool_results = []
        for block in response.content:
            if block.type != "tool_use" or block.name != "search":
                continue

            result = search(
                query=block.input["query"],
                max_results=block.input.get("max_results", 5)
            )
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result
            })

        # Send the tool results back to Claude
        messages = [
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results}
        ]

        # Get final response
        final_response = anthropic_client.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            messages=messages,
            tools=tools
        )

        return "".join(
            block.text for block in final_response.content
            if hasattr(block, "text")
        )

    # No tool use, return the response directly
    return "".join(
        block.text for block in response.content
        if hasattr(block, "text")
    )


# Example usage
if __name__ == "__main__":
    response = chat("What are the latest developments in quantum computing?")
    print(response)

How It Works

User sends a message - The user asks a question that may require search
Claude decides to search - The model determines if it needs external information
Tool use is returned - Claude returns a tool_use block with the search query
Seltz executes search - Your code calls Seltz with the query
Results sent back - Search results are sent as a tool_result
Final response - Claude generates a response using the search results

User Question → Claude → Tool Use → Seltz Search → Tool Result → Claude → Final Answer

Streaming Responses

Stream the final response for better user experience:

def chat_stream(user_message: str):
    """Send a message with streaming response."""
    messages = [{"role": "user", "content": user_message}]

    # Initial request (non-streaming to check for tool use)
    response = anthropic_client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        messages=messages,
        tools=tools
    )

    if response.stop_reason == "tool_use":
        # Every tool_use block needs its own tool_result in the next message,
        # and Claude may ask for several in one turn.
        tool_results = []
        for block in response.content:
            if block.type != "tool_use" or block.name != "search":
                continue

            result = search(
                query=block.input["query"],
                max_results=block.input.get("max_results", 5)
            )
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result
            })

        messages = [
            {"role": "user", "content": user_message},
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results}
        ]

        # Stream the final response
        with anthropic_client.messages.stream(
            model="claude-sonnet-5",
            max_tokens=4096,
            messages=messages,
            tools=tools
        ) as stream:
            for text in stream.text_stream:
                print(text, end="", flush=True)
        print()
    else:
        for block in response.content:
            if hasattr(block, "text"):
                print(block.text)

Multi-Turn Conversations

Maintain conversation history for follow-up questions:

import json

from anthropic import Anthropic
from seltz import Seltz


class SearchAssistant:
    def __init__(self):
        self.anthropic = Anthropic()
        self.seltz = Seltz()
        self.messages = []
        self.tools = [
            {
                "name": "search",
                "description": "Search the web.",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"},
                        "max_results": {"type": "integer"},
                    },
                    "required": ["query"],
                },
            }
        ]

    def search(self, query: str, max_results: int = 5) -> str:
        response = self.seltz.search(query, max_results=max_results)
        results = [
            {"url": doc.url, "content": doc.content}
            for doc in response.documents
        ]
        return json.dumps(results)

    def chat(self, user_message: str) -> str:
        self.messages.append({"role": "user", "content": user_message})

        response = self.anthropic.messages.create(
            model="claude-sonnet-5",
            max_tokens=4096,
            messages=self.messages,
            tools=self.tools
        )

        if response.stop_reason == "tool_use":
            # Add assistant response with tool use
            self.messages.append({"role": "assistant", "content": response.content})

            # Every tool_use block needs its own tool_result in the next
            # message, and Claude may ask for several in one turn.
            tool_results = []
            for block in response.content:
                if block.type != "tool_use" or block.name != "search":
                    continue

                result = self.search(
                    query=block.input["query"],
                    max_results=block.input.get("max_results", 5)
                )
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

            # Add the tool results
            self.messages.append({"role": "user", "content": tool_results})

            # Get final response
            final_response = self.anthropic.messages.create(
                model="claude-sonnet-5",
                max_tokens=4096,
                messages=self.messages,
                tools=self.tools
            )

            content = "".join(
                block.text for block in final_response.content
                if hasattr(block, "text")
            )
            self.messages.append({"role": "assistant", "content": content})
            return content

        # No tool use
        content = "".join(
            block.text for block in response.content
            if hasattr(block, "text")
        )
        self.messages.append({"role": "assistant", "content": response.content})
        return content


# Usage
assistant = SearchAssistant()
print(assistant.chat("What is quantum computing?"))
print(assistant.chat("Which companies are leading in this field?"))

Error Handling

Handle Seltz errors gracefully so Claude can respond appropriately:

from seltz import (
    Seltz,
    SeltzError,
    SeltzAuthenticationError,
    SeltzRateLimitError,
    SeltzTimeoutError,
)


def search(query: str, max_results: int = 5) -> str:
    """Execute search with error handling."""
    try:
        response = seltz_client.search(query, max_results=max_results)
        results = [
            {"url": doc.url, "content": doc.content}
            for doc in response.documents
        ]
        return json.dumps(results)
    except SeltzAuthenticationError:
        return json.dumps({"error": "Search authentication failed"})
    except SeltzRateLimitError:
        return json.dumps({"error": "Search rate limit exceeded, try again later"})
    except SeltzTimeoutError:
        return json.dumps({"error": "Search timed out"})
    except SeltzError as e:
        return json.dumps({"error": f"Search failed: {str(e)}"})

Best Practices

Write clear tool descriptions

Claude uses the description to decide when to use the tool. Be explicit about what information the search provides and when it should be used.

Limit results appropriately

More results mean more tokens and higher costs. Use max_results to balance comprehensiveness with efficiency.

Handle errors gracefully

Return error information as JSON so Claude can inform the user or suggest alternatives.

Use streaming for better UX

Stream the final response so users see output immediately rather than waiting for the complete response.

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Anthropic Tool Calling

Prerequisites

Installation

Setup

Define the Search Tool

Using the Messages API

How It Works

Streaming Responses

Multi-Turn Conversations

Error Handling

Best Practices

Next Steps

OpenAI Tool Calling

Agno Framework

​Prerequisites

​Installation

​Setup

​Define the Search Tool

​Using the Messages API

​How It Works

​Streaming Responses

​Multi-Turn Conversations

​Error Handling

​Best Practices

​Next Steps

OpenAI Tool Calling

Agno Framework

Prerequisites

Installation

Setup

Define the Search Tool

Using the Messages API

How It Works

Streaming Responses

Multi-Turn Conversations

Error Handling

Best Practices

Next Steps