Learn how to use the AI SDK's generateText function with Metorial-powered tools for agentic workflows.

Basic Usage

The generateText function runs a single AI completion with tool support:

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

metorial.withProviderSession(
  metorialAiSdk,
  { serverDeployments: ['your-deployment-id'] },
  async session => {
    let result = await generateText({
      model: openai('gpt-4o'),
      prompt: 'What are my upcoming meetings today?',
      maxSteps: 10,
      tools: session.tools
    });

    console.log(result.text);
  }
);

Understanding maxSteps

The maxSteps parameter controls how many times the AI can call tools:

• Low (1-3): For simple queries that need one or two tool calls
• Medium (5-10): For most use cases with moderate complexity
• High (10+): For complex tasks requiring multiple tool interactions

Example with different complexities:

// Simple query - needs just one tool call
let simple = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather today?',
  maxSteps: 3,
  tools: session.tools
});

// Complex query - may need multiple tool calls
let complex = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Summarize all GitHub issues assigned to me, check my calendar, and suggest which ones I should work on today',
  maxSteps: 15,
  tools: session.tools
});

Accessing Result Details

The result object contains useful information:

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Search my emails for messages about the Q4 project',
  maxSteps: 10,
  tools: session.tools
});

console.log('Final answer:', result.text);
console.log('Total steps taken:', result.steps?.length);
console.log('Finish reason:', result.finishReason);

How Tool Calling Works

1. AI Receives Prompt: The model analyzes your prompt
2. Decides to Use Tools: If needed, it chooses which Metorial tool to call
3. Tool Executes: Metorial handles the API call and returns results
4. AI Continues: The model uses the tool response to answer or call more tools
5. Final Response: After completing its task, the AI provides the final answer

Common Patterns

Information Retrieval

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Find the README.md file in the main repository and summarize it',
  maxSteps: 5,
  tools: session.tools
});

Multi-Step Tasks

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Create a new GitHub issue for the bug in the login flow, then send a Slack message to #engineering about it',
  maxSteps: 10,
  tools: session.tools
});

Data Analysis

let result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Analyze our team's GitHub activity for the past week and provide insights',
  maxSteps: 12,
  tools: session.tools
});

Tips for Better Results

• Be Specific: Clear prompts help the AI choose the right tools
• Set Appropriate maxSteps: Too low and the task might fail; too high wastes resources
• Test Iteratively: Start with simple prompts and gradually increase complexity
• Handle Errors: Wrap calls in try-catch blocks for production use