API Reference

Anthropic Claude tool use based on function docstrings.

class anthropic_tools.AnthropicTool(*args, **kwargs)

Protocol for Anthropic Tools.

Anthropic Tools are callable objects that can be used by Anthropic Claude, what sets them apart from a regular function is that they have a schema.

property interpret_as_response: bool: Check if the return value of the Anthropic Tool should be interpreted as the assistant’s response.

property name: str

Get the name of the Tool.

Returns:: The name of the Tool.

property save_return: bool: Check if the return value of the Tool should be added to the convo.

property schema: ToolParam

Get the schema of the Anthropic Tool.

Returns:: The schema of the Anthropic Tool.

property serialize: bool: Check if the return value of the Tool should be serialized.

exception anthropic_tools.AnthropicToolsError: Base class for exceptions raised by Anthropic Tools.

class anthropic_tools.ArgSchemaParser(argtype: Type[T], rec_parsers: list[Type[anthropic_tools.parsers.parser.ArgSchemaParser]])

A protocol for a parser for a specific argument type

Both converts the argument definition to a JSON schema and parses the argument value from JSON import

property argument_schema: dict[str, JsonType]: Parse an argument of a specific type

classmethod can_parse(argtype: Any) → TypeGuard[Type[T]]

Whether this parser can parse a specific arg type

Parameters:: argtype (Any) – The type to check

parse_rec(argtype: Type[S]) → ArgSchemaParser[S]

Parse a type recursively

Parameters:: argtype (Type[S]) – The type to parse
Returns:: The parser for the type
Return type:: ArgSchemaParser[S]
Raises:: CannotParseTypeError – If the type cannot be parsed

parse_value(value: JsonType) → T

Parse a value of a specific type

Parameters:: value (JsonType) – The value to parse
Raises:: BrokenSchemaError – If the value does not match the schema

class anthropic_tools.BasicToolSet(tools: list[anthropic_tools.tools.tools.AnthropicTool] | None = None)

A basic set of tools.

find_tool(tool_name: str) → AnthropicTool

Find a tool by its name.

Parameters:: tool_name – The name of the tool to find.
Returns:: The AnthropicTool object with the specified name.
Raises:: ToolNotFoundError – If the tool with the specified name is not found.

Get the result of running a tool with the given arguments.

Parameters:

tool – The AnthropicTool object representing the tool to run.
arguments – The arguments for the tool.

Returns:

A RawToolResult object representing the result of running the tool,: or None if the tool does not save the return value.

run_tool(input_data: ToolUseBlock | ToolUseBlockParam) → ToolResult

Run a tool with the given input data.

Parameters:: input_data – The input data for the tool, either as a ToolUseBlock or ToolUseBlockParam object.
Returns:: A ToolResult object representing the result of running the tool.
Raises:: BrokenSchemaError – If the input data does not match the tool’s schema.

property tools_schema: list[anthropic.types.beta.tools.tool_param.ToolParam]

Get the schema of all tools in the set, in the format the API expects.

Returns:: A list of ToolParam objects representing the schema of each tool.

exception anthropic_tools.BrokenSchemaError(response: Any, schema: Any)

The response from Anthropic does not match the schema.

response

The response that does not match the schema.

Type:: Any

schema

The schema that the response should match.

Type:: Any

exception anthropic_tools.CannotParseTypeError(argtype: Any)

The type of an argument cannot be parsed.

argtype

The type that cannot be parsed.

Type:: Any

class anthropic_tools.Conversation(client: Anthropic, skills: list[ToolSet] | None = None, model: str = 'claude-3-haiku-20240307', engine: str | None = None)

A conversation with Anthropic Claude with tools.

add_message(message: ToolsBetaMessageParam | str) → None

Add a message to the conversation.

Parameters:: message (ToolsBetaMessageParam | str) – The message to add.

add_messages(messages: list[anthropic.types.beta.tools.tools_beta_message_param.ToolsBetaMessageParam]) → None

Add multiple messages to the conversation.

Parameters:: messages (list[ToolsBetaMessageParam]) – The messages to add.

add_skill(skill: ToolSet) → None

Add a skill to the conversation.

Parameters:: skill (ToolSet) – The skill to add.

add_tool(tool: AnthropicTool) → AnthropicTool

add_tool(tool: Callable[[...], Any], *, name: str | None = None, description: str | None = None, save_return: bool = True, serialize: bool = True, interpret_as_response: bool = False) → Callable[[...], Any]

add_tool(*, name: str | None = None, description: str | None = None, save_return: bool = True, serialize: bool = True, interpret_as_response: bool = False) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

Add a tool to the conversation.

Parameters:

tool (AnthropicTool | Callable[..., Any] | None, optional) – The tool to add. Defaults to None.
name (str | None, optional) – The name of the tool. Defaults to None.
description (str | None, optional) – The description of the tool. Defaults to None.
save_return (bool, optional) – Whether to save the return value of the tool. Defaults to True.
serialize (bool, optional) – Whether to serialize the tool. Defaults to True.
interpret_as_response (bool, optional) – Whether to interpret the tool as a response. Defaults to False.

Returns:

The added tool, or a decorator that adds the tool.

Return type:

Callable[[Callable[…, Any]], Callable[…, Any]] | Callable[…, Any]

add_tool_result(tool_result: ToolResult) → bool

Add a tool result to the conversation.

Parameters:: tool_result (ToolResult) – The tool result to add.
Returns:: True if the tool result was added, False otherwise.
Return type:: bool

ask(question: str, retries: int | None = 1, max_tokens: int = 1024) → list[anthropic.types.beta.tools.tools_beta_message_param.ToolsBetaMessageParam]

Ask a question to Anthropic Claude.

Parameters:

question (str) – The question to ask.
retries (int | None, optional) – The number of retries. Defaults to 1.
max_tokens (int, optional) – The maximum number of tokens per message. Defaults to 1024.

Returns:

The response to the question.

clear_messages() → None: Clear all messages from the conversation.

generate_message(retries: int | None = 1, max_tokens=1024) → ToolsBetaMessageParam

Generate a message using Anthropic Claude.

Parameters:

retries (int | None, optional) – The number of retries. Defaults to 1.
max_tokens (int, optional) – The maximum number of tokens. Defaults to 1024.

Returns:

The generated message.

Return type:

ToolsBetaMessageParam

pop_message(index: int = -1) → ToolsBetaMessageParam

Pop a message

Parameters:: index (int) – The index. Defaults to -1.
Returns:: The popped message.
Return type:: ToolsBetaMessageParam

remove_tool(tool: str | AnthropicTool | Callable[..., Any]) → None

Remove a tool from the conversation.

Parameters:: tool (str | AnthropicTool | Callable[..., Any]) – The tool to remove.

run_tool_if_needed() → bool

Run a tool if needed.

Returns:: True if a tool was run, False otherwise.
Return type:: bool

run_until_response(retries: int | None = 1, max_tokens=1024) → list[anthropic.types.beta.tools.tools_beta_message_param.ToolsBetaMessageParam]

Run the conversation until a response is received.

Parameters:

retries (int | None, optional) – The number of retries. Defaults to 1.
max_tokens (int, optional) – The maximum number of tokens per message. Defaults to 1024.

Returns:

The response messages,: both from Claude and tools.

Return type:

list[ToolsBetaMessageParam]

property tools_schema: list[anthropic.types.beta.tools.tool_param.ToolParam]

Get the tools schema.

Returns:: The tools schema.
Return type:: list[ToolParam]

class anthropic_tools.ImageToolOutput(source: Source, type: Literal['image'] = 'image'): The image output of a tool.

class anthropic_tools.MutableToolSet(*args, **kwargs)

A protocol defining a mutable set of tools that can be used by Anthropic Claude.

add_tool(tool: AnthropicTool) → AnthropicTool

add_tool(tool: Callable[[...], Any], *, name: str | None = None, description: str | None = None, save_return: bool = True, serialize: bool = True, interpret_as_response: bool = False) → Callable[[...], Any]

add_tool(*, name: str | None = None, description: str | None = None, save_return: bool = True, serialize: bool = True, interpret_as_response: bool = False) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

Add a tool to the set.

Parameters:

tool – The tool to add.
name – The name of the tool.
description – The description of the tool.
save_return – Whether to save the return value of the tool.
serialize – Whether to serialize the return value of the tool.
interpret_as_response – Whether to interpret the return value as a response.

Returns:

The added tool or a decorator to add a callable tool.

remove_tool(tool: str | AnthropicTool | Callable[[...], Any]) → None

Remove a tool from the set.

Parameters:: tool – The tool to remove. It can be the name of the tool, an AnthropicTool, or a callable.

exception anthropic_tools.NonSerializableOutputError(result: Any)

The tool output is not JSON-serializable.

result

The result that is not JSON-serializable.

Type:: Any

class anthropic_tools.RawToolResult(result: Any, serialize: bool = True)

The raw result of an Anthropic Tool.

The raw result can be serialized and converted to content blocks.

Convert the raw result to content blocks.

Returns:: The content blocks representing the raw result.

property serialized: str

Serialize the raw result.

Returns:: The serialized raw result.
Raises:: NonSerializableOutputError – If the raw result cannot be serialized.

class anthropic_tools.TextToolOutput(content: str, is_error: bool = False, type: Literal['text'] = 'text'): The text output of a tool.

exception anthropic_tools.ToolNotFoundError(tool_name: str)

The requested tool is not found.

tool_name

The name of the tool that was not found.

Type:: str

class anthropic_tools.ToolResult(use_id: str, name: str, raw_result: RawToolResult, interpret_return_as_response: bool = False, response_role: Literal['user', 'assistant'] = 'user')

Represents the result of using an Anthropic Tool.

The result can include the content blocks and the interpreted return value.

Get the content blocks of the Tool Result. Only meaningful for tools that have interpret_return_as_response set to True. An example use case is a tool that returns image content blocks.

Returns:

The content blocks of the Tool Result,: or None if there is no raw result.

property content: str

Get the content of the Tool Result.

Returns:: The content of the Tool Result, or None if there is no raw result.

property result: Any | None

Get the result of the underlying function call.

Returns:: The raw result of the function call

class anthropic_tools.ToolSet(*args, **kwargs)

A protocol defining a set of tools that can be used by Anthropic Claude.

run_tool(input_data: ToolUseBlock | ToolUseBlockParam) → ToolResult

Run a tool from the set with the given input data.

Parameters:: input_data – The input data for the tool.

property tools_schema: list[anthropic.types.beta.tools.tool_param.ToolParam]: Get the schema of the tools in the set.

class anthropic_tools.ToolWrapper(func: Callable[[...], Any], config: WrapperConfig | None = None, name: str | None = None, description: str | None = None)

A wrapper that turns ordinary functions into Anthropic Tools.

property arg_docs: dict[str, str]

Get the dictionary of argument descriptions.

Returns:: The dictionary of argument descriptions.

property argument_parsers: OrderedDict[str, ArgSchemaParser]

Get the ordered dictionary of argument parsers.

Returns:: The ordered dictionary of argument parsers.

property arguments_schema: JsonType

Get the schema for the arguments.

Returns:: The schema for the arguments.

property interpret_as_response: bool

Get the flag indicating whether to interpret the result as a response.

Returns:: The flag indicating whether to interpret the result as a response.

property name: str

Get the name of the tool.

Returns:: The name of the tool.

parse_argument(argument: Parameter) → ArgSchemaParser

Parse the argument using the appropriate argument schema parser.

Parameters:: argument – The argument to be parsed.
Returns:: The argument schema parser.
Raises:: CannotParseTypeError – If the argument type is not supported.

parse_arguments(arguments: dict[str, JsonType]) → OrderedDict[str, Any]

Parse the arguments using the argument parsers.

Parameters:: arguments – The arguments to be parsed.
Returns:: The ordered dictionary of parsed arguments.
Raises:: BrokenSchemaError – If the arguments do not match the schema.

property parsed_docs: Docstring

Get the parsed docstring.

Returns:: The parsed docstring.

property parsers: list[Type[anthropic_tools.parsers.parser.ArgSchemaParser]]

Get the list of argument schema parsers.

Returns:: The list of argument schema parsers.

property required_arguments: list[str]

Get the list of required arguments.

Returns:: The list of required arguments.

property save_return: bool

Get the flag indicating whether to save the return value.

Returns:: The flag indicating whether to save the return value.

property schema: ToolParam

Get the schema for the tool.

Returns:: The schema for the tool.

property serialize: bool

Get the flag indicating whether to serialize the arguments.

Returns:: The flag indicating whether to serialize the arguments.

class anthropic_tools.UnionSkillSet(*sets: ToolSet)

A skill set that combines multiple tool sets.

add_skill(skill: ToolSet) → None

Add a tool set to the skill set.

Parameters:: skill – The tool set to be added.

run_tool(input_data: ToolUseBlock | ToolUseBlockParam) → ToolResult

Run a tool using the skill set.

Parameters:: input_data – The input data for the tool.
Returns:: The result of running the tool.

property tools_schema: list[anthropic.types.beta.tools.tool_param.ToolParam]

Get the schema of the tools in the skill set.

Returns:: The list of tool parameters.

class anthropic_tools.WrapperConfig(parsers: list[Type[anthropic_tools.parsers.parser.ArgSchemaParser]] | None = None, save_return: bool = True, serialize: bool = True, interpret_as_response: bool = False): Configuration options for the ToolWrapper.