Feedback wanted: Tool helpers

[felixfbecker]

As of 0.63.0, tool use helpers are available in beta in the SDK, which:

• Let you define tools as functions with type-safe input parameters with either Zod or JSON schema
• Have the SDK automatically call your functions and send tool results back
• Give you an agentic "tool loop" out of the box
• Let you customize conversation state and tool handling flexibly however you need (e.g. to implement context management strategies or special-case certain tool handling)

import { betaZodTool } from '@anthropic-ai/sdk/helpers/zod';
import { z } from 'zod';

const weatherTool = betaZodTool({
  name: 'get_weather',
  inputSchema: z.object({
    location: z.string(),
  }),
  description: 'Get the current weather in a given location',
  run: (input) => {
    return `The weather in ${input.location} is foggy and 60°F`;
  },
});

const runner = anthropic.beta.messages.toolRunner({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'What is the weather in San Francisco?' }],
  tools: [weatherTool],
});

for await (const message of runner) {
  console.log(message);
}

You can learn more in the documentation.

We would love to hear your feedback on these APIs!

• Are they intuitive?
• Do they make it easier to write agentic tool loops?
• Is anything missing for more complex use cases?
• Any other thoughts!

[coygeek]

This is a fantastic and much-needed feature in 0.63.0! Huge thanks to the team for shipping this. Like many others, we've been building tool-use loops manually, and this new toolRunner helper will eliminate a ton of boilerplate. It's a massive improvement for the developer experience.

To synthesize feedback and answer your questions directly:

• Are they intuitive?
  Yes, absolutely. The API is incredibly intuitive, especially the betaZodTool helper, which feels natural for any TypeScript developer. Using Zod for schema definition, validation, and getting static type safety in the run function is a brilliant choice.

• Do they make it easier to write agentic tool loops?
  Without a doubt. This abstracts away the entire manual cycle of checking for a tool_use stop reason, parsing tool calls, finding and executing the correct function, formatting the tool_result, and continuing the conversation. The for await...of runner pattern is a clean, modern way to handle this.

Here’s some synthesized feedback and a few questions for more complex use cases:

Key Questions & Suggestions

1. Streaming the Final Assistant Response: This was the most common question. The examples show the runner yielding complete BetaMessage objects at each step. For user-facing applications, it's crucial to stream the final text response (after all tool calls are complete) token-by-token. The example in tools-helpers-advanced-streaming.ts shows that setting stream: true makes the runner yield a BetaMessageStream for each turn, which is perfect! It would be incredibly helpful to feature a simpler version of this streaming pattern more prominently in the README.md or helpers.md, as it's a key feature for building responsive UIs.

2. Error Handling within Tools: What is the recommended pattern for handling errors inside a tool's run function? If a tool's implementation throws an error (e.g., throw new Error('API failed')), does the runner automatically catch it and format it into a tool_result block with is_error: true to send back to the model? That would be the ideal default behavior.

3. Parallel Tool Calls: How does the runner handle cases where the model requests multiple tools in a single turn? We assume it executes them concurrently (e.g., with Promise.all) and then sends all the results back in the next message. Confirmation of this, and perhaps a small example, would be great.

4. Advanced State Management: The setMessagesParams and pushMessages methods mentioned in the docs look incredibly powerful for building more complex agents. They seem perfect for handling state, recovering from errors, or injecting custom context mid-loop. An example showcasing this (e.g., catching a failed tool and pushing a message to the model to try a different approach) would be fantastic.

Specific Points & Clarifications

• Platform Support (Bedrock/Vertex): The changelog for 0.25.0 of @anthropic-ai/bedrock-sdk mentions "support for toolRunner helpers". Do these helpers work seamlessly with the AnthropicBedrock and AnthropicVertex clients as well? If so, this is a huge win for developers on those platforms.
• Documentation/Import Path: There's a small ambiguity in the import paths. The discussion post uses import { betaZodTool } from '@anthropic-ai/sdk/helpers/zod';, while helpers.md and the directory structure suggest the path is ...@anthropic-ai/sdk/helpers/beta/zod. A quick clarification would be helpful.
• Iteration vs. await: The docs show both iterating with for await...of runner and getting the final result directly with await runner. The mental model seems to be that iteration is for observing/acting on intermediate tool-use steps, while a direct await is for when you only need the final answer. This flexibility is excellent, and confirming this understanding would be great.

Overall, this is a brilliant and much-needed feature that strikes the perfect balance between a high-level, easy-to-use abstraction and the flexibility to handle advanced agentic logic when needed.

Really excited about this. Thanks again for the great work