From 80c93bd66835af3eff69d1290fdcdd5762e446fc Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Mon, 19 Jan 2026 20:11:53 +0800
Subject: [PATCH] feat: expose `maxSteps` config

---
 packages/core/src/PageAgentCore.ts                  | 13 +++++++------
 packages/core/src/config/constants.ts               |  3 +--
 packages/core/src/config/index.ts                   |  8 +++++++-
 .../pages/docs/advanced/page-agent-core/page.tsx    | 10 ++++++++--
 .../src/pages/docs/advanced/page-agent/page.tsx     |  2 +-
 5 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/packages/core/src/PageAgentCore.ts b/packages/core/src/PageAgentCore.ts
index f5e273c..baa00ce 100644
--- a/packages/core/src/PageAgentCore.ts
+++ b/packages/core/src/PageAgentCore.ts
@@ -8,7 +8,7 @@ import chalk from 'chalk'
 import zod from 'zod'
 
 import { type PageAgentConfig } from './config'
-import { MAX_STEPS } from './config/constants'
+import { DEFAULT_MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
 import {
@@ -49,7 +49,7 @@ export { tool, type PageAgentTool } from './tools'
  *    - Types: thinking, executing, executed, retrying, error
  */
 export class PageAgentCore extends EventTarget {
-	config: PageAgentConfig
+	config: PageAgentConfig & { maxSteps: number }
 	id = uid()
 	tools: typeof tools
 	disposed = false
@@ -86,7 +86,8 @@ export class PageAgentCore extends EventTarget {
 	constructor(config: PageAgentConfig & { pageController: PageController }) {
 		super()
 
-		this.config = config
+		this.config = { ...config, maxSteps: config.maxSteps || DEFAULT_MAX_STEPS }
+
 		this.#llm = new LLM(this.config)
 		this.tools = new Map(tools)
 		this.pageController = config.pageController
@@ -273,7 +274,7 @@ export class PageAgentCore extends EventTarget {
 				await onAfterStep.call(this, this.history)
 
 				step++
-				if (step > MAX_STEPS) {
+				if (step > this.config.maxSteps) {
 					this.#onDone('Step count exceeded maximum limit', false)
 					const result: ExecutionResult = {
 						success: false,
@@ -475,7 +476,7 @@ export class PageAgentCore extends EventTarget {
 		}
 
 		// Warn about remaining steps
-		const remaining = MAX_STEPS - stepCount
+		const remaining = this.config.maxSteps - stepCount
 		if (remaining === 5) {
 			this.pushObservation(
 				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
@@ -505,7 +506,7 @@ export class PageAgentCore extends EventTarget {
 			${this.task}
 			</user_request>
 			<step_info>
-			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
+			Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps
 			Current date and time: ${new Date().toISOString()}
 			</step_info>
 			</agent_state>
diff --git a/packages/core/src/config/constants.ts b/packages/core/src/config/constants.ts
index 42d3a29..10a0ffb 100644
--- a/packages/core/src/config/constants.ts
+++ b/packages/core/src/config/constants.ts
@@ -1,2 +1 @@
-// Agent-specific constants (LLM constants moved to @page-agent/llms)
-export const MAX_STEPS = 20
+export const DEFAULT_MAX_STEPS = 20
diff --git a/packages/core/src/config/index.ts b/packages/core/src/config/index.ts
index fa5ce60..3f3cbc8 100644
--- a/packages/core/src/config/index.ts
+++ b/packages/core/src/config/index.ts
@@ -1,5 +1,5 @@
 import type { LLMConfig } from '@page-agent/llms'
-import type { PageController, PageControllerConfig } from '@page-agent/page-controller'
+import type { PageControllerConfig } from '@page-agent/page-controller'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import type { PageAgentTool } from '../tools'
@@ -14,6 +14,12 @@ export interface AgentConfig {
 	// theme?: 'light' | 'dark'
 	language?: SupportedLanguage
 
+	/**
+	 * Maximum number of steps the agent can take per task.
+	 * @default 20
+	 */
+	maxSteps?: number
+
 	/**
 	 * Custom tools to extend PageAgent capabilities
 	 * @experimental
diff --git a/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
index 0588637..4f53ae1 100644
--- a/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
+++ b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
@@ -105,8 +105,8 @@ const result = await agent.execute('Fill in the form with test data')`}
 							type: 'string',
 							required: true,
 							description: isZh
-								? '模型名称（如 gpt-4o, claude-3.5-sonnet）'
-								: 'Model name (e.g., gpt-4o, claude-3.5-sonnet)',
+								? '模型名称（如 gpt-5.2, anthropic/claude-4.5-haiku）'
+								: 'Model name (e.g., gpt-5.2, anthropic/claude-4.5-haiku)',
 						},
 						{
 							name: 'temperature',
@@ -149,6 +149,12 @@ const result = await agent.execute('Fill in the form with test data')`}
 							defaultValue: "'en-US'",
 							description: isZh ? 'Agent 输出语言' : 'Agent output language',
 						},
+						{
+							name: 'maxSteps',
+							type: 'number',
+							defaultValue: '20',
+							description: isZh ? '每个任务的最大步骤数' : 'Maximum number of steps per task',
+						},
 						{
 							name: 'customTools',
 							type: 'Record<string, PageAgentTool | null>',
diff --git a/packages/website/src/pages/docs/advanced/page-agent/page.tsx b/packages/website/src/pages/docs/advanced/page-agent/page.tsx
index 0aecff7..356d7ef 100644
--- a/packages/website/src/pages/docs/advanced/page-agent/page.tsx
+++ b/packages/website/src/pages/docs/advanced/page-agent/page.tsx
@@ -53,7 +53,7 @@ const agent = new PageAgent({
   // LLM Configuration (required)
   baseURL: 'https://api.openai.com/v1',
   apiKey: 'your-api-key',
-  model: 'gpt-4o',
+  model: 'gpt-5.2',
   
   // Optional settings
   language: 'en-US',