When using Metorial with Vercel's AI SDK, the framework handles most tool execution automatically. This guide explains how tool calling works and how to customize the behavior.

Automatic Tool Execution

The AI SDK can automatically execute tools for you:

import { generateText } from 'ai';

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    const result = await generateText({
      model: yourModel,
      messages: [{ role: 'user', content: 'Check my calendar for today' }],
      tools: session.tools,
      maxSteps: 5 // Allow multiple tool calls
    });
    
    console.log(result.text);
  }
);

The maxSteps parameter controls how many times the AI can call tools before returning a final response.

Streaming Responses

For real-time updates, use streaming:

import { streamText } from 'ai';

await metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    const result = streamText({
      model: yourModel,
      messages: [{ role: 'user', content: 'Search my emails from last week' }],
      tools: session.tools,
      maxSteps: 5
    });
    
    for await (const chunk of result.textStream) {
      process.stdout.write(chunk);
    }
  }
);

Manual Tool Execution

If you need more control, you can handle tool calls manually:

const result = await generateText({
  model: yourModel,
  messages: messages,
  tools: session.tools,
  maxSteps: 1 // Only allow one step
});

// Check if there are tool calls
if (result.toolCalls && result.toolCalls.length > 0) {
  // Execute tools through Metorial
  const toolResults = await session.callTools(result.toolCalls);
  
  // Continue conversation with tool results
  // ...
}

Understanding the Flow

1. Your user sends a message
2. The AI SDK sends the message and available tools to the model
3. The model decides which tools to call (if any)
4. Metorial executes the tool calls through your configured integrations
5. Results are returned to the model
6. The model generates a final response

Error Handling

Always wrap tool calls in try-catch blocks:

try {
  const result = await generateText({
    model: yourModel,
    messages: messages,
    tools: session.tools,
    maxSteps: 5
  });
  console.log(result.text);
} catch (error) {
  console.error('Tool execution failed:', error);
}