On April 4th, 2024, Anthropic released official support for tool use through their API. This feature allows developers to define one or more tools that include parameters, descriptions, and schema definitions for Claude to process.
In this post, we’ll go over how to leverage these tools using the Python Anthropic SDK.
Claude with tools example in Python
Firstly, ensure that your Anthropic API key is available as an environment variable in your shell:
Install the Anthropic SDK
Next, install the latest version of the Anthropic SDK using pip.
Define the tools
Using the provided JSON schema example in the Anthropic documentation, let’s define a get_current_stock_price tool:
“name”: “get_current_stock_price”,
“description”: “Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.”,
“input_schema”: {
“type”: “object”,
“properties”: {
“ticker”: {
“type”: “string”,
“description”: “The stock ticker symbol, e.g. AAPL for Apple Inc.”
}
},
“required”: [“ticker”]
}
}
In Python,
tools = [
{
“name“: “get_current_stock_price“,
“description“: “Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.“,
“input_schema“: {
“type“: “object“,
“properties“: {
“symbol“: {
“type“: “string“,
“description“: “The stock ticker symbol, e.g. AAPL for Apple Inc.“
}
},
“required“: [“symbol“]
}
}
]
Instantiate a client
To invoke Claude, we need to instantiate a client. The SDK uses the ANTHROPIC_API_KEY environment variable by default for authentication.
client = anthropic.Anthropic()
Invoke Claude with tools
Now, let’s create a new message using Claude and the tools:
tools = [
{
“name“: “get_current_stock_price“,
“description“: “Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.“,
“input_schema“: {
“type“: “object“,
“properties“: {
“symbol“: {
“type“: “string“,
“description“: “The stock ticker symbol, e.g. AAPL for Apple Inc.“
}
},
“required“: [“symbol“]
}
}
]
client = anthropic.Anthropic()
response = client.beta.tools.messages.create(
model=“claude-3-haiku-20240307“,
max_tokens=1024,
tools=tools,
messages=[
{
“role“: “user“,
“content“: “What is the stock price of Apple?“
}
]
)
print(response)
Output:
The output includes a ToolUseBlock with the input for the tool. We now need to process the tool and return the result to Claude.
Building a tool router
Let’s build a mock function that returns 150.0 for the stock price:
# Fake implementation for demonstration purposes
return 150.0
And then a “router” function that accepts the tool name and input:
match tool_name:
case “get_current_stock_price“:
return get_current_stock_price(input[“symbol“])
case _:
raise ValueError(f“Unknown tool: {tool_name}“)
Responding with a tool result example
Anthropic provides a Jupyter notebook that showcases a customer service example using tools. We’ll adapt some of the functionality to our script:
tool_use = next(block for block in response.content if block.type == “tool_use“)
tool_name = tool_use.name
tool_input = tool_use.input
tool_result = process_tool(tool_name, tool_input)
messages = [
{“role“: “user“, “content“: user_message},
{“role“: “assistant“, “content“: response.content},
{
“role“: “user“,
“content“: [
{
“type“: “tool_result“,
“tool_use_id“: tool_use.id,
“content“: str(tool_result),
}
],
},
]
response = client.beta.tools.messages.create(
model=model,
max_tokens=4096,
tools=tools,
messages=messages
)
final_response = next(
(block.text for block in response.content if isinstance(block, TextBlock)),
None,
)
The code does the following:
Loop while the response is tool_use
Extracts the current tool’s name and input
Processes the tool by calling the router function
Creates a new Claude message using the prior messages and the tool result
Retrieves the final response from Claude and returns the text
Putting it altogether
Here’s the resulting code:
from anthropic.types import TextBlock
client = anthropic.Anthropic()
def talk(client, tools, model, user_message):
response = client.beta.tools.messages.create(
model=model,
max_tokens=1024,
tools=tools,
messages=[{“role“: “user“, “content“: user_message}],
)
while response.stop_reason == “tool_use“:
tool_use = next(block for block in response.content if block.type == “tool_use“)
tool_name = tool_use.name
tool_input = tool_use.input
tool_result = process_tool(tool_name, tool_input)
messages = [
{“role“: “user“, “content“: user_message},
{“role“: “assistant“, “content“: response.content},
{
“role“: “user“,
“content“: [
{
“type“: “tool_result“,
“tool_use_id“: tool_use.id,
“content“: str(tool_result),
}
],
},
]
response = client.beta.tools.messages.create(
model=model, max_tokens=4096, tools=tools, messages=messages
)
final_response = next(
(block.text for block in response.content if isinstance(block, TextBlock)),
None,
)
return final_response
def get_current_stock_price(symbol: str):
# Fake implementation for demonstration purposes
return 150.0
def process_tool(tool_name: str, input):
match tool_name:
case “get_current_stock_price“:
return get_current_stock_price(input[“symbol“])
case _:
raise ValueError(f“Unknown tool: {tool_name}“)
if __name__ == “__main__“:
client = anthropic.Anthropic()
tools = [
{
“name“: “get_current_stock_price“,
“description“: “Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.“,
“input_schema“: {
“type“: “object“,
“properties“: {
“symbol“: {
“type“: “string“,
“description“: “The stock ticker symbol, e.g. AAPL for Apple Inc.“,
}
},
“required“: [“symbol“],
},
}
]
response = talk(
client, tools, “claude-3-haiku-20240307“, “What is the price of Apple?“
)
print(response)
Here is the output:
Conclusion
In this post, we covered:
How to invoke Claude using tools
How to process tool calls using a switch statement
How to respond with a tool_result so that Claude can output a final answer
The purpose of this post was to get you started by providing a foundational understanding of Anthropic tool usage using the Python SDK. For more information about tool best practices or multi-tool chaining, please refer to Anthropic’s documentation.