anthropic_gleam - v0.1.0

anthropic/tools

Tool use utilities for handling the complete tool workflow

This module provides utilities for:

Tool Use Workflow

  1. Send a request with tools defined
  2. Claude responds with tool_use blocks (stop_reason: “tool_use”)
  3. Extract tool calls from the response
  4. Execute the tools and collect results
  5. Send a new request with tool_result blocks
  6. Claude responds with the final answer

Example

// Step 1: Create request with tools
let request = create_request(model, messages, max_tokens)
  |> with_tools([weather_tool])

// Step 2: Get response
let response = api.create_message(client, request)

// Step 3: Check for tool use and extract calls
case needs_tool_execution(response) {
  True -> {
    let tool_calls = extract_tool_calls(response)
    // Step 4: Execute tools and build results
    let results = list.map(tool_calls, fn(call) {
      let result = execute_my_tool(call.name, call.input)
      tool_success(call.id, result)
    })
    // Step 5: Continue conversation with tool results
    let messages = build_tool_result_messages(response, results)
    let next_request = create_request(model, messages, max_tokens)
    api.create_message(client, next_request)
  }
  False -> response
}

Values

all_tools_succeeded

</> 
pub fn all_tools_succeeded(
  results: List(tool.ToolResult),
) -> Bool

Check if all tool results are successful

any_tools_failed

</> 
pub fn any_tools_failed(results: List(tool.ToolResult)) -> Bool

Check if any tool results failed

build_continuation_messages

</> 
pub fn build_continuation_messages(
  assistant_response: request.CreateMessageResponse,
  tool_results: List(tool.ToolResult),
) -> List(message.Message)

Simplified version: build messages from just the response and results Assumes original messages are tracked elsewhere

build_tool_result_messages

</> 
pub fn build_tool_result_messages(
  original_messages: List(message.Message),
  assistant_response: request.CreateMessageResponse,
  tool_results: List(tool.ToolResult),
) -> List(message.Message)

Build the complete message list for continuing a conversation after tool use This includes the original messages, the assistant’s tool use response, and the user’s tool results

count_tool_calls

</> 
pub fn count_tool_calls(
  response: request.CreateMessageResponse,
) -> Int

Count the number of tool calls in a response

create_tool_result_message

</> 
pub fn create_tool_result_message(
  results: List(tool.ToolResult),
) -> message.Message

Create a user message with tool results

dispatch_tool_call

</> 
pub fn dispatch_tool_call(
  call: tool.ToolCall,
  handlers: List(#(String, fn(String) -> Result(String, String))),
) -> tool.ToolResult

Match a tool call by name and execute the appropriate handler Returns an error message if no handler matches

dispatch_tool_calls

</> 
pub fn dispatch_tool_calls(
  calls: List(tool.ToolCall),
  handlers: List(#(String, fn(String) -> Result(String, String))),
) -> List(tool.ToolResult)

Dispatch multiple tool calls using a handler map

execute_tool_calls

</> 
pub fn execute_tool_calls(
  calls: List(tool.ToolCall),
  handler: fn(tool.ToolCall) -> Result(String, String),
) -> List(tool.ToolResult)

Execute a handler function on each tool call and collect results The handler should return Ok(content) for success or Error(message) for failure

extract_tool_calls

</> 
pub fn extract_tool_calls(
  response: request.CreateMessageResponse,
) -> List(tool.ToolCall)

Extract all tool calls from a response

failure_for_call

</> 
pub fn failure_for_call(
  call: tool.ToolCall,
  error: String,
) -> tool.ToolResult

Create a failed tool result for a specific tool call

get_error_message

</> 
pub fn get_error_message(
  result: tool.ToolResult,
) -> option.Option(String)

Get the error message from a ToolResult if it’s a failure

get_failures

</> 
pub fn get_failures(
  results: List(tool.ToolResult),
) -> List(tool.ToolResult)

Get all failed tool results

get_first_tool_call

</> 
pub fn get_first_tool_call(
  response: request.CreateMessageResponse,
) -> Result(tool.ToolCall, Nil)

Get the first tool call from a response

get_success_content

</> 
pub fn get_success_content(
  result: tool.ToolResult,
) -> option.Option(String)

Get the content from a ToolResult if it’s a success

get_successes

</> 
pub fn get_successes(
  results: List(tool.ToolResult),
) -> List(tool.ToolResult)

Get all successful tool results

get_tool_call_by_id

</> 
pub fn get_tool_call_by_id(
  response: request.CreateMessageResponse,
  tool_id: String,
) -> Result(tool.ToolCall, Nil)

Extract a specific tool call by ID

get_tool_calls_by_name

</> 
pub fn get_tool_calls_by_name(
  response: request.CreateMessageResponse,
  tool_name: String,
) -> List(tool.ToolCall)

Extract tool calls by name

get_tool_names

</> 
pub fn get_tool_names(
  response: request.CreateMessageResponse,
) -> List(String)

Get all unique tool names from a response

has_tool_call

</> 
pub fn has_tool_call(
  response: request.CreateMessageResponse,
  tool_name: String,
) -> Bool

Check if a response contains a specific tool call

map_tool_calls

</> 
pub fn map_tool_calls(
  calls: List(tool.ToolCall),
  handler: fn(tool.ToolCall) -> tool.ToolResult,
) -> List(tool.ToolResult)

Execute a handler that returns a ToolResult directly

needs_tool_execution

</> 
pub fn needs_tool_execution(
  response: request.CreateMessageResponse,
) -> Bool

Check if a response requires tool execution Returns True if stop_reason is ToolUse

success_for_call

</> 
pub fn success_for_call(
  call: tool.ToolCall,
  content: String,
) -> tool.ToolResult

Create a successful tool result for a specific tool call

tool_result_to_content_block

</> 
pub fn tool_result_to_content_block(
  result: tool.ToolResult,
) -> message.ContentBlock

Create a tool result content block from a ToolResult

✨ Search Document