Skip to main content
What you’ll learn:
  • How to install the Metorial SDK
  • Available AI providers and integrations
  • How to create sessions and use tools
  • OAuth flow for authenticated services
  • Streaming and session management
Before you begin:References:

​
Prerequisites

  1. Metorial API key: Get one from app.metorial.com
  2. Server deployment ID: Deploy a server (e.g., Exa for search)
  3. AI provider API key: OpenAI, Anthropic, Google, etc.

​
Installation

Install the core SDK and a provider package for your AI model: 
# Install the core SDK
npm install metorial

# Install a provider package (choose one or more)
npm install @metorial/ai-sdk      # Vercel AI SDK (recommended)
npm install @metorial/anthropic   # Anthropic Claude
npm install @metorial/openai      # OpenAI
npm install @metorial/google      # Google Gemini
npm install @metorial/mistral     # Mistral
npm install @metorial/deepseek    # DeepSeek
We support OpenAI, Anthropic, Google, Mistral, DeepSeek, and any OpenAI-compatible API. See the TypeScript SDK and Python SDK repos for all available providers.

​
Your First AI Agent

import { Metorial } from 'metorial';
import { metorialAiSdk } from '@metorial/ai-sdk';
import { anthropic } from '@ai-sdk/anthropic';
import { streamText } from 'ai';

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

await metorial.withProviderSession(
    metorialAiSdk,
    {
        serverDeployments: [{ serverDeploymentId: 'your-deployment-id' }],
        streaming: true
    },
    async ({ tools, closeSession }) => {
        let result = streamText({
            model: anthropic('claude-sonnet-4-5'),
            prompt: 'Search for the latest AI research',
            tools,
            onFinish: async () => {
                await closeSession();
            }
        });

        for await (let textPart of result.textStream) {
            process.stdout.write(textPart);
        }
    }
);

​
OAuth Flow

For services requiring user authentication (Slack, GitHub, Google Calendar), use OAuth sessions: 
import { Metorial } from 'metorial';
import { metorialAnthropic } from '@metorial/anthropic';

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

// 1. Create OAuth sessions for each service
let slackOAuth = await metorial.oauth.sessions.create({
    serverDeploymentId: 'your-slack-deployment-id',
    callbackUrl: 'https://yourapp.com/oauth/callback'
});

let calendarOAuth = await metorial.oauth.sessions.create({
    serverDeploymentId: 'your-google-cal-deployment-id',
    callbackUrl: 'https://yourapp.com/oauth/callback'
});

// 2. Send OAuth URLs to your user
console.log('Authorize Slack:', slackOAuth.url);
console.log('Authorize Calendar:', calendarOAuth.url);

// 3. Wait for user to complete OAuth
await metorial.oauth.waitForCompletion([slackOAuth.id, calendarOAuth.id]);

// 4. Use authenticated sessions
await metorial.withProviderSession(
    metorialAnthropic,
    {
        serverDeployments: [
            {
                serverDeploymentId: 'your-slack-deployment-id',
                oauthSessionId: slackOAuth.id
            },
            {
                serverDeploymentId: 'your-google-cal-deployment-id',
                oauthSessionId: calendarOAuth.id
            },
            {
                serverDeploymentId: 'your-exa-deployment-id' // No OAuth needed
            }
        ]
    },
    async ({ tools, closeSession }) => {
        // Use tools from all three services
        await closeSession();
    }
);

​
Session Options

​
Streaming Mode

Enable streaming when using tool calls with streaming responses: 
await metorial.withProviderSession(
    metorialAiSdk,
    {
        serverDeployments: ['your-deployment-id'],
        streaming: true // Required for streaming with tool calls
    },
    async ({ tools, closeSession }) => {
        // Your streaming code
        await closeSession();
    }
);

​
Closing Sessions

Always close your session when done to free up resources: 
async ({ tools, closeSession }) => {
    // Use tools...

    // For streaming, close in onFinish callback:
    let result = streamText({
        tools,
        onFinish: async () => {
            await closeSession();
        }
    });

    // Or close directly when done:
    await closeSession();
}

​
Error Handling

import { MetorialAPIError } from 'metorial';

try {
    await metorial.withProviderSession(/* ... */);
} catch (error) {
    if (error instanceof MetorialAPIError) {
        console.error(`API Error: ${error.message} (Status: ${error.status})`);
    } else {
        console.error('Unexpected error:', error);
    }
}

​
What’s Next?

OAuth Integration

Handle user authorization for services like Slack and GitHub.

Provider Examples

Use with OpenAI, Anthropic, Google, and more.