Learn how to properly handle tool calls from your AI model and process the responses from Metorial integrations.

The Basic Flow

When using Metorial with the AI SDK, the typical flow is:

1. Send a message to the AI model with tools available
2. The model decides which tools to call (if any)
3. You execute those tool calls through Metorial
4. You send the results back to the model
5. The model uses the results to form its final response

Using generateText with Tools

The simplest approach uses the AI SDK's generateText function:

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    const result = await generateText({
      model: openai('gpt-4'),
      messages: [
        { role: 'user', content: 'Schedule a meeting for tomorrow at 2pm' }
      ],
      tools: session.tools,
      maxToolRoundtrips: 5 // Allow up to 5 rounds of tool calls
    });
    
    console.log(result.text);
  }
);

The AI SDK automatically handles tool calls and responses when using generateText with tools.

Manual Tool Call Handling

For more control, you can manually handle the tool call loop:

import { generateText } from 'ai';

const messages = [
  { role: 'user', content: 'What tasks are due today?' }
];

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    for (let i = 0; i < 10; i++) {
      const result = await generateText({
        model: openai('gpt-4'),
        messages,
        tools: session.tools,
        maxToolRoundtrips: 0 // Disable automatic tool calling
      });
      
      // Check if the model wants to call tools
      if (result.toolCalls && result.toolCalls.length > 0) {
        // Call tools through Metorial
        const toolResponses = await session.callTools(result.toolCalls);
        
        // Add to message history
        messages.push(
          { role: 'assistant', toolCalls: result.toolCalls },
          ...toolResponses
        );
        continue;
      }
      
      // No more tool calls - we have the final answer
      console.log(result.text);
      break;
    }
  }
);

Understanding Tool Responses

Tool responses from Metorial contain the results of integration calls. The session.callTools method automatically formats these responses for the AI SDK.

Error Handling

Always wrap your tool calls in try-catch blocks:

try {
  const result = await generateText({
    model: openai('gpt-4'),
    messages,
    tools: session.tools
  });
  console.log(result.text);
} catch (error) {
  console.error('Error during generation:', error.message);
  // Handle the error appropriately
}

Best Practices

• Set reasonable maxToolRoundtrips to prevent infinite loops
• Log tool calls during development to understand agent behavior
• Handle errors gracefully and provide fallback responses
• Consider setting timeouts for long-running operations