OpenAI Tool Calling

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

Prerequisites

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

Installation

pip install openai seltz

Setup

Set your API keys as environment variables:

export OPENAI_API_KEY="your-openai-key"
export SELTZ_API_KEY="your-seltz-key"

Initialize both clients:

from openai import OpenAI
from seltz import Seltz

openai_client = OpenAI()
seltz_client = Seltz()

Define the Search Tool

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

tools = [
    {
        "type": "function",
        "function": {
            "name": "search",
            "description": "Search for information on the web. Returns relevant documents with URLs and content.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query"
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return (default: 5)",
                        "default": 5
                    }
                },
                "required": ["query"]
            }
        }
    }
]

Using Chat Completions API

Here’s a complete example using OpenAI’s Chat Completions API with Seltz search:

import json
from openai import OpenAI
from seltz import Seltz

# Initialize clients
openai_client = OpenAI()
seltz_client = Seltz()

# Define the search tool
tools = [
    {
        "type": "function",
        "function": {
            "name": "search",
            "description": "Search for information on the web. Returns relevant documents with URLs and content.",
            "parameters": {
                "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 = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
        tool_choice="auto"
    )

    assistant_message = response.choices[0].message

    # Check if the model wants to call a tool
    if assistant_message.tool_calls:
        # Add assistant message to conversation
        messages.append(assistant_message)

        # Process each tool call
        for tool_call in assistant_message.tool_calls:
            if tool_call.function.name == "search":
                # Parse arguments and execute search
                args = json.loads(tool_call.function.arguments)
                result = search(
                    query=args["query"],
                    max_results=args.get("max_results", 5)
                )

                # Add tool result to conversation
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })

        # Get final response with search results
        final_response = openai_client.chat.completions.create(
            model="gpt-4o",
            messages=messages
        )
        return final_response.choices[0].message.content

    return assistant_message.content


# 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
OpenAI decides to search - The model determines if it needs external information
Tool call is made - OpenAI returns a tool call with the search query
Seltz executes search - Your code calls Seltz with the query
Results sent back - Search results are added to the conversation
Final response - OpenAI generates a response using the search results

User Question → OpenAI → Tool Call → Seltz Search → Results → OpenAI → Final Answer

Streaming Responses

For a better user experience, stream the final response:

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

    # Initial request
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools,
        tool_choice="auto"
    )

    assistant_message = response.choices[0].message

    if assistant_message.tool_calls:
        messages.append(assistant_message)

        for tool_call in assistant_message.tool_calls:
            if tool_call.function.name == "search":
                args = json.loads(tool_call.function.arguments)
                result = search(
                    query=args["query"],
                    max_results=args.get("max_results", 5)
                )
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": result
                })

        # Stream the final response
        stream = openai_client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            stream=True
        )

        for chunk in stream:
            if chunk.choices[0].delta.content:
                print(chunk.choices[0].delta.content, end="", flush=True)
        print()
    else:
        print(assistant_message.content)

Multi-Turn Conversations

Maintain conversation history for follow-up questions:

import json

from openai import OpenAI
from seltz import Seltz


class SearchAssistant:
    def __init__(self):
        self.openai = OpenAI()
        self.seltz = Seltz()
        self.messages = []
        self.tools = [
            {
                "type": "function",
                "function": {
                    "name": "search",
                    "description": "Search the web.",
                    "parameters": {
                        "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.openai.chat.completions.create(
            model="gpt-4o",
            messages=self.messages,
            tools=self.tools,
            tool_choice="auto"
        )

        assistant_message = response.choices[0].message

        if assistant_message.tool_calls:
            self.messages.append(assistant_message)

            for tool_call in assistant_message.tool_calls:
                if tool_call.function.name == "search":
                    args = json.loads(tool_call.function.arguments)
                    result = self.search(
                        query=args["query"],
                        max_results=args.get("max_results", 5)
                    )
                    self.messages.append({
                        "role": "tool",
                        "tool_call_id": tool_call.id,
                        "content": result
                    })

            final_response = self.openai.chat.completions.create(
                model="gpt-4o",
                messages=self.messages
            )
            content = final_response.choices[0].message.content
            self.messages.append({"role": "assistant", "content": content})
            return content

        self.messages.append(assistant_message)
        return assistant_message.content


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

Error Handling

Handle Seltz errors gracefully so the model 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

The description helps OpenAI decide when to use the tool. Be specific about what the search returns and when it should be used.

Limit results appropriately

More results mean more tokens. Use max_results to balance comprehensiveness with cost and latency.

Handle errors gracefully

Return error information as JSON so the model can inform the user or try alternative approaches.

Use streaming for better UX

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

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

OpenAI Tool Calling

Prerequisites

Installation

Setup

Define the Search Tool

Using Chat Completions API

How It Works

Streaming Responses

Multi-Turn Conversations

Error Handling

Best Practices

Next Steps

Anthropic Tool Calling

Agno Framework

​Prerequisites

​Installation

​Setup

​Define the Search Tool

​Using Chat Completions API

​How It Works

​Streaming Responses

​Multi-Turn Conversations

​Error Handling

​Best Practices

​Next Steps

Anthropic Tool Calling

Agno Framework

Prerequisites

Installation

Setup

Define the Search Tool

Using Chat Completions API

How It Works

Streaming Responses

Multi-Turn Conversations

Error Handling

Best Practices

Next Steps