feat(ai): extend addToolResult to support error results

[aron]

Background

Currently the addToolResult() helper allows a user to update a pending tool call evaluated on the client. However, there is not currently a mechanism for being able to report a pending tool call as errored with a state of output-error.

We would like to be able to use this to report client side errors with failed tool calls as well as cancellations.

There doesn't appear to be a way to replicate the behavior of the addToolResult implementation using just the public API provided by useChat.

So as a workaround we currently have to use addToolResult and add an additional typed field on our tool output with status: "success" | "error" and consider failed tool calls "output" then adapt the rendering in our application. This differs to how we handle server side errors with tool calls which will use the output-error state.

const { messages, sendMessage, addToolResult } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
  }),

  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,

  // run client-side tools that are automatically executed:
  async onToolCall({ toolCall }) {
    // Check if it's a dynamic tool first for proper type narrowing
    if (toolCall.dynamic) {
      return;
    }

    if (toolCall.toolName === 'getWeatherInformation') {
      try {
        const weather = await getWeatherInformation(toolCall.input);

        // No await - avoids potential deadlocks
        addToolResult({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          output: {
            status: "success",
            value: cities[Math.floor(Math.random() * cities.length)],
          }
        });
      } catch (err) {
        addToolResult({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          output: {
            status: "error",
            value: "Failed to get weather information",
          }
        });
      }
    }
  },
});

Then in our UI code when handling the tool part:

const status = useMemo((): React.ReactNode => {
  if (cancelled) {
    return <ErrorIcon />;
  }

  switch (state) {
    case "input-available":
    case "input-streaming":
      return (
        <Spinner />
      );
    case "output-available":
      // Duplicate error handling.
      if (output.type === "error") {
        return (
          <ErrorIcon />
        );
      }
      return (
        <SuccessIcon />
      );
    case "output-error":
      return (
        <ErrorIcon />
      );
    default:
      const exhaustive: never = state;
      throw new Error(`Unexpected state: ${exhaustive}`);
  }
}, [state, output, cancelled]);

Summary

This commit extends the addToolResult method on the AbstractChat class to optionally take an output-error result. This allows clients to report both successful and failed tool calls using the same mechanism.

addToolResult({ tool, toolCallId, state: "output-error", errorText: "Failed" });

For backwards compatibility the existing method interface is still supported and will default to a state of output-available.

addToolResult({ tool, toolCallId, output: "Success!" });

So my earlier example becomes:

const { messages, sendMessage, addToolResult } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
  }),

  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,

  // run client-side tools that are automatically executed:
  async onToolCall({ toolCall }) {
    // Check if it's a dynamic tool first for proper type narrowing
    if (toolCall.dynamic) {
      return;
    }

    if (toolCall.toolName === 'getWeatherInformation') {
      try {
        const weather = await getWeatherInformation(toolCall.input);

        // No await - avoids potential deadlocks
        addToolResult({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          output: cities[Math.floor(Math.random() * cities.length)],
        });
      } catch (err) {
        addToolResult({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          state: "output-error",
          errorText: "Failed to get weather information",
        });
      }
    }
  },
});

Integration style tests have been added to the existing chat.test.ts suite to exercise the new behavior in the same fashion as the current implementation.

It also updates the lastAssistantMessageIsCompleteWithToolCalls helper function to also consider tool parts with a state of output-error a completed tool call. This ensures consistent behavior for both types of result.

Notes on implementation

I've extended addToolResult to keep the API footprint minimal but I would appreciate feedback on whether an additional method e.g. addToolError({ tool, toolCallId, errorText }) would be a more appropriate solution. I'm happy to change the code if needed.

const { messages, sendMessage, addToolResult } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
  }),

  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,

  // run client-side tools that are automatically executed:
  async onToolCall({ toolCall }) {
    // Check if it's a dynamic tool first for proper type narrowing
    if (toolCall.dynamic) {
      return;
    }

    if (toolCall.toolName === 'getWeatherInformation') {
      try {
        const weather = await getWeatherInformation(toolCall.input);

        // No await - avoids potential deadlocks
        addToolResult({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          output: cities[Math.floor(Math.random() * cities.length)],
        });
      } catch (err) {
        addToolError({
          tool: 'getWeatherInformation',
          toolCallId: toolCall.toolCallId,
          errorText: "Failed to get weather information",
        });
      }
    }
  },
});

Manual Verification

I couldn't figure out how to correctly npm link the @ai-sdk/react and ai packages into our local project so we're currently running the it with a monkey patched version of addToolResult and lastAssistantMessageIsCompleteWithToolCalls copy & pasted into our codebase.

Tasks

• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• Formatting issues have been fixed (run pnpm prettier-fix in the project root)
• I have reviewed this pull request (self-review)

Future Work

None

Related Issues

None

[gr2m]

Hi Aron 👋🏼 thanks for the pull request! It's a great, especially given that it's your first 👏🏼

@lgrammel and I looked at it today. The CI is failing and we had some thoughts on how to improve the code, we thought the easiest would be to just push the changes we suggest: e218283 let us know what you think.

I would appreciate feedback on whether an additional method e.g. addToolError({ tool, toolCallId, errorText }) would be a more appropriate solution

We think the best solution would be to keep it at one method, but to rename it from addToolResult to addToolOutput, which would also better align with our overall naming convention. We can do that in a follow up to this pull request.

As a side note, we are looking deeper into tool calling right now, in particular in regard of human-in-the-loop. Stay tuned!

[gr2m]

@nicoalbanese can you please review the docs updates?

[aron]

@lgrammel and I looked at it today. The CI is failing and we had some thoughts on how to improve the code, we thought the easiest would be to just push the changes we suggest: e218283 let us know what you think.

Changes look great, the argument types are much clearer now. I've integrated them into this branch and force pushed.

As a side note, we are looking deeper into tool calling right now, in particular in regard of human-in-the-loop. Stay tuned!

Fantastic, looking forward to it!

[nicoalbanese]

Can we cut all the markup of the component? the important thing to highlight here is the onToolCall and addToolResult state.

[aron]

Done 👍 I wasn't sure if the examples were intended to be fully-working examples.

[nicoalbanese]

@gr2m happy with this once comments are resolved!

[aron]

Thanks both, I've made the requested changes and rebased.