How to Configure maxSteps to Limit Agent Execution Depth in PageAgent

The maxSteps configuration option caps the number of reasoning cycles an agent can perform per task at 40 by default, and can be customized via the AgentConfig interface when instantiating PageAgentCore or through the browser extension's React hook.

The alibaba/page-agent repository uses this safeguard to prevent infinite loops during autonomous web navigation. By configuring maxSteps appropriately, you control computational costs and ensure tasks terminate gracefully when they require excessive interaction cycles.

How maxSteps Works in the Core Architecture

The execution depth limit is enforced through three coordinated components in the core package.

Type Definition in AgentConfig

The optional field is declared in the public interface at packages/core/src/types.ts:

export interface AgentConfig extends LLMConfig {
    // ...
    /**
     * Maximum number of steps the agent can take per task.
     * @default 40
     */
    maxSteps?: number
    // ...
}

Default Value Assignment

When PageAgentCore initializes, it normalizes the value to 40 if omitted. In packages/core/src/PageAgentCore.ts at lines 98-100:

this.config = { ...config, maxSteps: config.maxSteps ?? 40 }

Enforcement in the Execution Loop

The main execution loop aborts when the step counter exceeds the configured limit. In packages/core/src/PageAgentCore.ts at lines 31-35:

if (step > this.config.maxSteps) {
    const errorMessage = 'Step count exceeded maximum limit'
    // ...
}

Methods to Configure maxSteps

Depending on your integration approach, you can set this limit programmatically or through the UI.

Direct Core Library Configuration

When using @page-agent/core directly, pass maxSteps within the constructor options:

import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'

const controller = new PageController()
const agent = new PageAgentCore({
  pageController: controller,
  maxSteps: 20,            // Limit to 20 steps per task
  // ... other LLM configuration
})

Browser Extension Advanced Settings

The extension exposes maxSteps through the useAgent React hook. The configuration interface in packages/extension/src/agent/useAgent.ts defines:

export interface AdvancedConfig {
  maxSteps?: number
  systemInstruction?: string
  experimentalLlmsTxt?: boolean
}

The configure function persists this to Chrome's local storage:

const configure = async ({ maxSteps, systemInstruction, ... }: ExtConfig) => {
  const advancedConfig: AdvancedConfig = { maxSteps, systemInstruction, ... }
  await chrome.storage.local.set({ advancedConfig })
}

When building the agent, the hook merges this into the core configuration:

const { systemInstruction, ...agentConfig } = config
const agent = new MultiPageAgent({
  ...agentConfig,
  instructions: systemInstruction ? { system: systemInstruction } : undefined,
})

Demo Configuration Defaults

For first-time users running the demo, edit packages/extension/src/agent/constants.ts to include a maxSteps field in the DEMO_CONFIG constant.

Behavior When Exceeding the Limit

When the step counter surpasses the configured maxSteps, the core pushes an error event to the history with type: 'error' and the message "Step count exceeded maximum limit". The agent status transitions to 'error', and the UI displays this termination reason.

Practical Configuration Examples

Limiting Steps in Core Library Usage

import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'

const controller = new PageController()
await controller.init()

const agent = new PageAgentCore({
  pageController: controller,
  maxSteps: 15,                       // Stop after 15 steps
  apiKey: process.env.OPENAI_KEY,
  model: 'gpt-4o-mini',
})

await agent.execute('Book the cheapest flight from Beijing to Shanghai')

Updating maxSteps from Extension UI

import { useAgent } from '@page-agent/extension/agent'

export function SettingsPanel() {
  const { config, configure } = useAgent()

  const handleChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    await configure({ ...config!, maxSteps: Number(e.target.value) })
  }

  return (
    <label>
      Max steps per task:
      <input
        type="number"
        min={1}
        max={100}
        defaultValue={config?.maxSteps ?? 40}
        onBlur={handleChange}
      />
    </label>
  )
}

Temporary Override for Single Execution

const agent = new MultiPageAgent({
  pageController,
  maxSteps: 5,               // Temporary strict limit
  // ... other config
})

await agent.execute('Click the Accept Cookies button')

Summary

• The maxSteps option in AgentConfig controls the maximum reasoning cycles per task, defaulting to 40 in packages/core/src/PageAgentCore.ts.
• Configure it programmatically by passing a number to the PageAgentCore or MultiPageAgent constructor.
• In the browser extension, use the useAgent hook's configure function to persist the setting via Chrome storage.
• When the limit is reached, the agent emits an error event with the message "Step count exceeded maximum limit" and terminates execution.

Frequently Asked Questions

What is the default maxSteps value in PageAgent?

The default value is 40. This is applied in packages/core/src/PageAgentCore.ts using the nullish coalescing operator: config.maxSteps ?? 40.

How does PageAgent enforce the maxSteps limit?

During execution, the core increments a step counter for each reasoning cycle. When step > this.config.maxSteps, the loop aborts and emits an error event with the message "Step count exceeded maximum limit", as implemented in the execute method of PageAgentCore.

Can I change maxSteps after initializing the agent?

No. The maxSteps value is assigned during construction in PageAgentCore.ts and stored in the immutable config object. To use a different limit, instantiate a new agent instance with the desired configuration.

Where is maxSteps stored in the browser extension?

The extension persists maxSteps within the advancedConfig object in Chrome's local storage, managed by the configure function in packages/extension/src/agent/useAgent.ts. This value is merged into the core agent configuration when the MultiPageAgent is instantiated.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}