@standardagents/xai

xAI provider for Standard Agents.

This package integrates xAI chat and image models through the Standard Agents provider interface. It uses the official @ai-sdk/xai integration under the hood and handles:

• text generation and streaming
• multimodal chat requests with image inputs
• local function tools on supported Grok models
• xAI reasoning controls where supported
• image generation and edit-style requests
• usage and cost extraction from xAI API responses

Install

npm install @standardagents/xai @standardagents/spec

Usage

import { xai } from '@standardagents/xai';

const provider = xai({
  apiKey: process.env.XAI_API_KEY!,
});

const result = await provider.generate({
  model: 'grok-4-0709',
  messages: [
    { role: 'user', content: 'Write a short tagline for a robotics startup.' },
  ],
});

console.log(result.content);
console.log(result.usage?.cost);

Factory

The package exports:

• xai(config) - provider factory
• XAIProvider - provider class
• xaiProviderOptions - Zod schema for provider-specific options

Factory config:

type ProviderFactoryConfig = {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
};

Supported Features

Depending on the model, the provider supports:

• streaming chat
• images in chat input
• local function tool calling
• JSON mode
• reasoning controls
• image generation output

The package includes a curated static catalog for current xAI text and image models, including Grok aliases.

const models = await provider.getModels?.();
const capabilities = await provider.getModelCapabilities?.('grok-4.20-0309-reasoning');

Provider Options

Common xAI-specific provider options:

• reasoningEffort
• logprobs
• topLogprobs
• parallel_function_calling
• searchParameters
• aspect_ratio
• output_format
• sync_mode
• resolution
• quality
• numberOfImages

Example:

const result = await provider.generate({
  model: 'grok-4-0709',
  messages: [{ role: 'user', content: 'Search the web and summarize today in one paragraph.' }],
  providerOptions: {
    reasoningEffort: 'high',
    searchParameters: {
      mode: 'auto',
      returnCitations: true,
      sources: [{ type: 'web', safeSearch: true }],
    },
  },
});

Images

For chat models, the provider translates Standard Agents image parts and image attachments into xAI image inputs. For xAI image generation models, it routes image requests through the image generation path and returns generated image attachments in the Standard Agents response format.

Cost Data

When xAI returns cost_in_usd_ticks, this package converts it to USD and attaches the monetary value to usage.cost. That means xAI responses can log actual API-reported cost instead of relying only on token-price fallback tables.

Debugging

Use inspectRequest() to view the xAI-native request body that will be sent to the provider:

const inspected = await provider.inspectRequest?.({
  model: 'grok-4.20-0309-non-reasoning',
  messages: [{ role: 'user', content: 'hello' }],
});

console.log(inspected?.body);

Notes

• xAI tool choice translation is normalized to the shapes expected by the xAI SDK.
• Non-image generic file parts are not supported in xAI chat requests; image parts are supported.
• Some moving aliases such as grok-4 and grok-4-latest are resolved to the current snapshot IDs internally.