xAI

Use xAI Grok through Responses (default) or Chat Completions. Responses preserves provider-native reasoning state and supports hosted search tools. BeamWeaver supplies chat integration, not an xAI embedding adapter.

Setup and first request

import Config
config :beam_weaver, :xai, api_key: System.fetch_env!("XAI_API_KEY")

Put configuration in your application's runtime file, then make an actual call:

alias BeamWeaver.Core.{ChatModel, Message}
{:ok, model} = BeamWeaver.Models.init_chat_model("xai:grok-4.3", max_tokens: 512, timeout: 120_000)
{:ok, reply} = ChatModel.invoke(model, "Explain parcel tracking in one sentence.")
true = byte_size(Message.text(reply)) > 0
true = reply.usage_metadata.total_tokens > 0

The example pins its model rather than relying on a changing provider default. The same identifier works in an agent's model declaration.

Options and endpoint differences

Stop sequences are supported only on nonreasoning Chat Completions models. Request metadata is not accepted; use trace metadata for application labels. On Chat Completions, tool-returned images/PDFs move to a following user message; on Responses they remain in the tool result.

Reasoning

BeamWeaver requests encrypted reasoning content on Responses for reasoning models and replays it unchanged. This also permits full-history continuation with store: false. An explicit raw include override can replace automatic include fields, so preserve required items when customizing requests.

Responses usage may include context_details for the latest server-side agent step. BeamWeaver exposes its input-plus-output count as usage_metadata.context_tokens for context budgeting while retaining cumulative total_tokens for billing.

Chat Completions has no equivalent encrypted reasoning field. Do not reduce saved messages to visible text when the next request needs provider-native continuation state.

Choose a supported effort setting and execute the model:

defmodule MyApp.SupportAgent do
  use BeamWeaver.Agent

  model "xai:grok-4.6", reasoning_effort: :low, timeout: 120_000
  system_prompt "You are Acme's support agent."
end

{:ok, result} = MyApp.SupportAgent.invoke(%{messages: ["Reply with the word ready."]})
true = byte_size(result.messages |> List.last() |> BeamWeaver.Core.Message.text()) > 0

Server tools

A hosted tool executes at xAI. This example checks that search was actually requested by the provider response, not just declared:

{:ok, searched} =
  ChatModel.invoke(
    model,
    "Use web search to find the official Elixir programming language website and return its URL.",
    tools: [BeamWeaver.XAI.Tools.web_search()]
  )

true = byte_size(Message.text(searched)) > 0
true = Enum.any?(List.wrap(searched.content), &(Map.get(&1, :type) == :web_search_call))

Other implemented declarations include X search, code execution, collection/ file search and remote MCP. Account resources such as vector-store IDs must come from actual provisioning. Chat Completions supports function tools; use Responses for hosted search. Tools explains application-run actions and their separate execution loop. Generated file references returned by Chat Completions are available in response_metadata.output_files, including in collected streams.

Stored conversations

use_previous_response_id: true can send only new messages after a compatible stored Responses reply. Replies from another provider/API or from store: false are sent as history instead. A stored response ID is remote state; account retention and availability apply. Keep your application's conversation data when you need independent recovery.

Use the complete stored reply when continuing. The second call must recall the earlier order:

alias BeamWeaver.Core.{ChatModel, Message}

{:ok, model} = BeamWeaver.Models.init_chat_model("xai:grok-4.6", timeout: 120_000)
history = [Message.user("My order number is A-1001.")]
{:ok, reply} = ChatModel.invoke(model, history, use_previous_response_id: true)

# Sends only the new question, with the id of `reply`.
{:ok, answer} =
  ChatModel.invoke(model, history ++ [reply, Message.user("Which order did I mention?")],
    use_previous_response_id: true
  )

true = Message.text(answer) =~ "A-1001"

Prompt caching

The agent's prompt_caching declaration derives a stable key. Responses sends its key and conversation header; Chat Completions accepts both as well. Read actual cache usage to establish hits. The caching guide distinguishes provider prefix caching from skipping a whole model call.

Set the caching hint on the actual Chat Completions model. Caching is still subject to provider eligibility:

defmodule MyApp.SupportAgent do
  use BeamWeaver.Agent

  model "xai:grok-4.6", api: :chat_completions, timeout: 120_000
  system_prompt "Refunds take five business days. Explain the policy briefly."
  prompt_caching true
end

{:ok, result} = MyApp.SupportAgent.invoke(%{messages: ["Reply with the word ready."]})
true = byte_size(result.messages |> List.last() |> BeamWeaver.Core.Message.text()) > 0

Embeddings

Use an implemented embedding integration such as OpenAI for retrieval alongside a Grok chat model. There is no xAI embedding model to initialize through BeamWeaver. Image/video/voice generation APIs are also outside this chat integration.

Models

Limits are local profile data. A dash means not applicable or not recorded, not an unlimited allowance.

This is the checked-in compatibility registry, including snapshots. It does not imply every account can invoke every identifier. Verify your selected model with real calls and review provider capacity errors separately from invalid requests.

Further reading

The official xAI tools reference describes hosted tool requirements. Use Testing for deterministic failures and replay.