Configuration

Using the CLI?

If you're using the shiplightai CLI, SDK configuration is handled automatically. This page is for direct SDK usage.

SDK Configuration

Configure global settings with configureSdk(). Call once at startup before creating agents.

import { configureSdk, LogLevel } from "@shiplightai/sdk";

configureSdk({
  env: {
    GOOGLE_API_KEY: process.env.GOOGLE_API_KEY!,
  },
  logLevel: LogLevel.INFO,
});

The SDK does not automatically read provider credentials from process.env. Pass each required value through configureSdk({ env }).

Options

Option	Type	Default	Description
env	Record<string, string>	—	Runtime configuration and credentials
logLevel	LogLevel	INFO	DEBUG, INFO, WARN, ERROR, or SILENT
debugAgent	boolean	false	Enable detailed agent logging
agentLogPath	string	—	Path for agent log file
consoleLogsPath	string	—	Path for captured console logs
testResultsJsonPath	string	—	Path for test results JSON
stderrOnly	boolean	false	Route SDK log output to stderr

configureSdk() applies a partial update to the process-wide configuration. Use getSdkConfig() to read a copy of the current configuration.

Agent Configuration

import { createAgent } from "@shiplightai/sdk";

const agent = createAgent({
  model: "claude-haiku-4-5",
  computer_use_model: "claude-sonnet-4-6",
  variables: { username: "test@example.com" },
  sensitiveKeys: ["password"],
  testDataDir: "./test-data",
  downloadDir: "./downloads",
});

model is required. The provider is inferred from the model name, or you can use an explicit provider:model value such as openai:gpt-4o.

Agent options

Option	Type	Default	Description
model	string	—	Required primary model
computer_use_model	string	model	Model for computer-use operations
variables	Record<string, unknown>	{}	Initial variables
sensitiveKeys	string[]	[]	Keys withheld from LLM context and masked in logs
testDataDir	string	—	Base directory for upload fixtures
downloadDir	string	—	Directory for downloads

Environment Variables

Variable	Description
ANTHROPIC_API_KEY	Direct key for claude-* models
GOOGLE_API_KEY	Direct key for gemini-* models
OPENAI_API_KEY	Direct key for gpt-*, o1*, o3*, o4*, and similar models
SHIPLIGHT_API_TOKEN	Shiplight proxy token; can be used instead of a provider key

Provide one credential that can serve the selected model. A matching direct provider key takes precedence over SHIPLIGHT_API_TOKEN.

Additional routing options

Variable	Description
OPENAI_BASE_URL	OpenAI-compatible base URL; requires OPENAI_API_KEY
SHIPLIGHT_API_URL	Override the Shiplight proxy base URL
GOOGLE_GENAI_USE_VERTEXAI	Set to "true" to route Gemini through Vertex AI
ANTHROPIC_MODELS_USE_VERTEXAI	Set to a truthy value to route Claude through Vertex AI
GOOGLE_CLOUD_PROJECT	Required project when a Vertex route is enabled
GOOGLE_CLOUD_LOCATION	Required Vertex location

Vertex routing uses the model's normal gemini-* or claude-* name plus the flags above. Although vertex:, azure:, and bedrock: are recognized model prefixes, those explicit providers are not implemented and will throw.

Variables

Variables are key-value pairs that can be used in instructions as $variableName, ${variableName}, or {{ variableName }}.

// Set variables
agent.setVariable("username", "test@example.com");
agent.setVariable("password", "secret", true); // withheld from LLM context

// Use in instructions
await agent.act(page, "Fill username with {{ username }}");

// Read back
const value = agent.getVariable("username");

// Extract from page
await agent.extract(page, "the order total", "orderTotal");

createAgent({ variables, sensitiveKeys }) sets initial variables. Calling setVariable() again with sensitive: false removes an existing variable's sensitive designation.

Public exports

The package exports:

• Runtime values: createAgent, Agent, VariableStore, z, configureSdk, getSdkConfig, and LogLevel
• Types: CreateAgentOptions, LoginOptions, StepOptions, RunOptions, AgentStepResult, ICustomAction, ActionExecutionContext, CustomActionResult, and SdkConfig