# How to Configure maxSteps to Limit Agent Execution Depth in PageAgent

> Learn how to configure maxSteps in PageAgent to limit agent execution depth. Customize reasoning cycles for efficient task management and prevent infinite loops.

- Repository: [Alibaba/page-agent](https://github.com/alibaba/page-agent)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/alibaba/page-agent/blob/main/packages/core/src/types.ts):

```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`](https://github.com/alibaba/page-agent/blob/main/packages/core/src/PageAgentCore.ts) at lines 98-100:

```ts
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`](https://github.com/alibaba/page-agent/blob/main/packages/core/src/PageAgentCore.ts) at lines 31-35:

```ts
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:

```ts
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`](https://github.com/alibaba/page-agent/blob/main/packages/extension/src/agent/useAgent.ts) defines:

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

```

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

```ts
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:

```ts
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`](https://github.com/alibaba/page-agent/blob/main/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

```ts
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

```tsx
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

```ts
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`](https://github.com/alibaba/page-agent/blob/main/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`](https://github.com/alibaba/page-agent/blob/main/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`](https://github.com/alibaba/page-agent/blob/main/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`](https://github.com/alibaba/page-agent/blob/main/packages/extension/src/agent/useAgent.ts). This value is merged into the core agent configuration when the `MultiPageAgent` is instantiated.