anthropics/anthropic-tools

anthropics/anthropic-tools

Language: Python

Stars: 390

Forks: 56

Open issues: 13

Created: 2023-10-05T21:52:17Z

Pushed: 2024-11-04T23:34:50Z

Default branch: main

Fork: no

Archived: yes

README: > ⚠️ DEPRECATION NOTICE > > This repository is deprecated and no longer maintained. For up-to-date information on using tools with Claude, please refer to our official documentation at: > https://docs.anthropic.com/en/docs/build-with-claude/tool-use > > The official API provides a more robust, supported, and production-ready implementation of tool use functionality.

anthropic-tools

A repo for using tools/function calling with Anthropic models.

This SDK is Currently in Alpha and meant ONLY AS A RESEARCH PREVIEW. We promise no ongoing support. It is not intended for production use. Production-ready function calling support is coming to the Anthropic API soon.

Setup

Set your Anthropic API key as an environment variable:

# MacOS
export ANTHROPIC_API_KEY={your_anthropic_api_key}

If you are accessing Claude through AWS Bedrock, set the following enviroment variables instead:

# MacOS
export AWS_ACCESS_KEY_ID={your_AWS_access_key_id}
export AWS_SECRET_ACCESS_KEY={your_AWS_secret_access_key}
export AWS_SESSION_TOKEN={your_AWS_session_token}

[Optional] If you want to test the Brave search tool, set your Brave API key as an enviroment variable (get a key here):

# MacOS
export BRAVE_API_KEY={your_brave_api_key}

Create a Python Virtual Environment:

# MacOS
python3 -m venv anthropictools
source anthropictools/bin/activate

Install Requirements:

pip install -r requirements.txt

Getting Started

anthropic-tools follows a very simple architecture that lets users define and use tools with Claude. There are two classes users should be familiar with: BaseTool and ToolUser.

Additionally, anthropic-tools introduces a new *structured* prompt format that you will want to pay close attention to. This should make for easier prompt construction and parsing.

anthropic-tools also supports a number of pre-built tools out of the box, built on top of the same primitives available to you. These are here in case you want even easier tool use for some of our most common tools, such as search or SQL.

BaseTool

BaseTool is the class that should be used to define individual tools. All you need to do to create a tool is inherit BaseTool and define the use_tool() method for the tool.

import datetime, zoneinfo
from tool_use_package.tools.base_tool import BaseTool

class TimeOfDayTool(BaseTool):
"""Tool to get the current time of day."""
def use_tool(self, time_zone):
# Get the current time
now = datetime.datetime.now()

# Convert to the specified time zone
tz = zoneinfo.ZoneInfo(time_zone)
localized_time = now.astimezone(tz)

return localized_time.strftime("%H:%M:%S")

Then, you simply instantiate your custom tool with name (the name of the tool), description (the description Claude reads of what the tool does), and parameters (the parameters that the tool accepts). Pay attention to the formatting of each.

tool_name = "get_time_of_day"
tool_description = "Retrieve the current time of day in Hour-Minute-Second format for a specified time zone. Time zones should be written in standard formats such as UTC, US/Pacific, Europe/London."
tool_parameters = [
{"name": "time_zone", "type": "str", "description": "The time zone to get the current time for, such as UTC, US/Pacific, Europe/London."}
]

time_of_day_tool = TimeOfDayTool(tool_name, tool_description, tool_parameters)

ToolUser

ToolUser is passed a list of tools (child classes of BaseTool) and allows you to use Claude with those tools. To create a ToolUser instance simply pass it a list of one or more tools.

from tool_use_package.tool_user import ToolUser
time_tool_user = ToolUser([time_of_day_tool])

You can then make use of your ToolUser by calling its use_tools() method and passing in your desired prompt. Setting execution mode to "automatic" makes it execute the function; in the default "manual" mode it returns the function arguments back to the client to be executed there.

messages = [{'role': 'user', 'content': 'What time is it in Los Angeles?'}]
time_tool_user.use_tools(messages, execution_mode='automatic')

If you are accesing Claude through AWS Bedrock, set the parameter first_party to False (it is by default set to True):

time_tool_user = ToolUser([time_of_day_tool], first_party=False)

NOTE: If using bedrock, this SDK only supports claude 2.1 (anthropic.claude-v2:1).

Notice that new messages format instead of passing in a simple prompt string? Never seen it before? Don't worry, we are about to walk through it.

Prompt Format

Anthropic-tools uses a *structured* prompt input and output format, coming as a list of messages, intending to mimic our Messages API format. Let's take a quick tour of how to work with this list.

messages is a python list of message dictionaries. A single message dictionary object can contain these fields but will never contain all of them (see the field comments below for more detail on what this means):

{
"role": str, # The role of the message. 'user' for a message from the user, 'assistant' for a message from the assistant, 'tool_inputs' for a request from the assistant to use tools, 'tool_outputs' for a response to a tool_inputs message containing the results of using the specified tools in the specified ways.
"content": str, # The (non tool use) content of the message, which must be present for messages where role=(user, assistant, tool_inputs) and can not be present for messages where role=tool_outputs.
"tool_inputs": list[dict], # A list of dictionaries (see below). Must be specified in messages where role=tool_inputs.
"tool_outputs": list[dict], # A list of tool_output dictionaries (see below). One of tool_outputs or tool_error must be specified in messages where role=tool_outputs, but the other must be specified as None.
"tool_error": str # A tool error message corresponding to the first tool that errored to help Claude understand what it did wrong. One of tool_error or tool_outputs must be specified when role=tool_outputs, but the other must be specified as None.
}

tool_inputs is a list of dictionaries, where each dictionary represents a tool to use (at the 'tool_name' key), and the…