#Model configuration

Midscene reads all model configuration from operating-system environment variables.

Midscene integrates the OpenAI SDK by default for AI calls. The SDK defines the parameter shape, and most model providers (or deployment tools) offer compatible endpoints.

This doc focuses on Midscene model configuration. For how we choose models, see Model strategy. For quick recipes for popular models, see Common model configuration.

#Required settings

You need to set a default model for Midscene; see Model strategy for details.

#Advanced settings (optional)

Note: Control replanning behavior with the agent option replanningCycleLimit (defaults to 20, or 40 for vlm-ui-tars), not with environment variables.

#Configure a dedicated Insight model

Set the following if the Insight intent needs a different model:

#Configure a dedicated Planning model

Set the following if the Planning intent needs a different model:

#Debug logging switches

Enable the following variables to print richer debug logs. Regardless of the switches, logs are also saved under ./midscene_run/log.

#Still-compatible configs (not recommended)

The following environment variables are deprecated but still compatible. We recommend migrating to the new configuration approach.

#Planning model configuration

#General configuration

#Configure settings via JavaScript

You can configure models for each agent in JavaScript. See the API reference for details.

const agent = new Agent(page, {
  // Configure via modelConfig
  modelConfig: {
    MIDSCENE_MODEL_TIMEOUT: '60000', // 60 seconds
    MIDSCENE_MODEL_NAME: 'qwen3-vl-plus',
    // ... other configurations
  }
});

#FAQ

#How can I monitor token usage?

Set DEBUG=midscene:ai:profile:stats to print usage and latency.

You can also find usage statistics inside the generated report files.

#Using LangSmith

LangSmith is a platform for debugging large language models. Midscene provides auto-integration support - just install the dependency and set environment variables.

Step 1: Install dependency

npm install langsmith

Step 2: Set environment variables

# Enable Midscene's LangSmith auto-integration
export MIDSCENE_LANGSMITH_DEBUG=1

# LangSmith configuration
export LANGCHAIN_API_KEY="your-langchain-api-key-here"
export LANGCHAIN_TRACING=true
export LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"
# export LANGCHAIN_ENDPOINT="https://eu.api.smith.langchain.com" # If signed up in the EU region

After starting Midscene, you should see logs similar to:

DEBUGGING MODE: langsmith wrapper enabled

Notes:

• LangSmith and Langfuse can be enabled simultaneously.
• Node.js only; browser environments will throw errors.
• If you use createOpenAIClient, it overrides the env-based auto-integration.

For finer-grained control (e.g., enabling LangSmith only for specific tasks), use createOpenAIClient to wrap the client manually.

#Using Langfuse

Langfuse is another popular LLM observability platform. Integration is similar to LangSmith.

Step 1: Install dependency

npm install langfuse

Step 2: Set environment variables

# Enable Midscene's Langfuse auto-integration
export MIDSCENE_LANGFUSE_DEBUG=1

# Langfuse configuration
export LANGFUSE_PUBLIC_KEY="your-langfuse-public-key-here"
export LANGFUSE_SECRET_KEY="your-langfuse-secret-key-here"
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 EU region
# export LANGFUSE_BASE_URL="https://us.cloud.langfuse.com" # 🇺🇸 US region

After starting Midscene, you should see logs similar to:

DEBUGGING MODE: langfuse wrapper enabled

Notes:

• LangSmith and Langfuse can be enabled simultaneously.
• Node.js only; browser environments will throw errors.
• If you use createOpenAIClient, it overrides the env-based auto-integration.