Multi-turn conversations with tools

Overview

• Goal is to wire up multiple different tools to Claude, not just one
• Users may ask queries requiring multiple sequential tool calls to answer
• Application must handle chains of tool calls, not just single calls

Example: Multi-Step Tool Use

• User asks: "What day is 103 days from today? "
• Claude needs to call getCurrentDateTime first, then addDurationToDateTime
• Process: Claude requests tool → we execute it → pass result back → Claude may request another tool → repeat until final answer

Key Design Principle

• Cannot predict what users will ask, so must assume Claude might need multiple tools in sequence
• After each Claude response, check if it's requesting a tool use
• If no tool use requested, response is final and ready for user
• If tool use requested, execute tool, add result to conversation, and call Claude again

Pseudo-Code Pattern

Refactoring Steps Required

Step 1: Upgrade Helper Functions

• Update addUserMessage and addAssistantMessage to handle multiple message blocks
• Currently they only handle plain text blocks
• Need flexibility to accept: plain strings, lists of blocks, or entire message objects
• Import message type from anthropic. types
• Check if input is a Message object; if so, use its content property; otherwise use input directly

Step 2: Update Chat Function

• Add tools parameter (defaulted to None) to receive list of tool schemas
• Pass tools parameter to client. messages. create() call
• Change return value: instead of returning just first text block, return entire message object
• Reason: responses may contain multiple blocks (text + tool use blocks)

Step 3: Add Helper Function

• Create text_from_message() helper function
• Extracts all text blocks from a message and joins them together
• Replaces convenience of old single-text-block assumption
• Makes it easier to get text content from multi-block messages

Step 4: Implement runConversation Function

• Main function to handle multiple sequential tool calls
• Takes list of messages as input
• Continues calling Claude until no tool use is requested
• Executes tools and feeds results back into conversation loop

Takeaways

• Claude can handle multiple sequential tool calls in one conversation; the application must loop, executing each tool and passing results back until Claude stops requesting tools
• After each Claude response, check if it's requesting a tool use—if not, return the final answer; if yes, execute the tool, add the result to messages, and call Claude again
• Upgrade helper functions to handle multiple message blocks (not just plain text), pass tools parameter to the API call, and return the entire message object instead of just the first text block
• Create a text_from_message() helper to extract all text blocks from multi-block messages
• Implement a runConversation() loop that continues calling Claude until no tool use is requested, executing tools and feeding results back into the conversation