When using Metorial with OpenAI, your AI agent can call tools to access integrations. This guide explains how to handle those tool calls.

How Tool Calling Works

1. You provide available tools to OpenAI
2. OpenAI decides when to call a tool based on the conversation
3. You execute the tool call using Metorial
4. You send the results back to OpenAI
5. OpenAI uses the results to continue the conversation

Complete Example

import { Metorial } from 'metorial';
import { metorialOpenAI } from '@metorial/openai';
import OpenAI from 'openai';

const metorial = new Metorial({
  apiKey: process.env.METORIAL_API_KEY
});

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

await metorial.withProviderSession(
  metorialOpenAI.chatCompletions,
  { serverDeployments: ['your-server-deployment-id'] },
  async session => {
    let messages = [
      { role: 'user', content: 'What are my upcoming meetings today?' }
    ];

    // Initial request with tools
    let response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages,
      tools: session.tools
    });

    // Check if the model wants to call tools
    let toolCalls = response.choices[0]?.message.tool_calls;
    
    if (toolCalls) {
      // Execute the tool calls through Metorial
      let toolResponses = await session.callTools(toolCalls);
      
      // Add assistant's message and tool responses to conversation
      messages.push(
        { role: 'assistant', tool_calls: toolCalls },
        ...toolResponses
      );
      
      // Get final response with tool results
      response = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages,
        tools: session.tools
      });
    }

    console.log(response.choices[0]?.message.content);
  }
);

Key Points

• session.tools provides the formatted tools to OpenAI
• session.callTools() executes the tool calls and returns properly formatted responses
• Always add both the assistant's tool calls and the tool responses to your message history
• The model may make multiple tool calls in succession