chore: agent system prompt (#38752)

Author: pavelfeldman

docs/src/api/class-page.md

@@ -745,6 +745,11 @@ Maximum number of agentic turns to take per call. Defaults to 10.
 
 Secrets to hide from the LLM.
 
+### option: Page.agent.systemPrompt
+* since: v1.58
+- `systemPrompt` <[string]>
+
+System prompt for the agent's loop.
 
 ## async method: Page.bringToFront
 * since: v1.8

packages/playwright-client/types/types.d.ts

@@ -2143,6 +2143,11 @@ export interface Page {
      * Secrets to hide from the LLM.
      */
     secrets?: { [key: string]: string; };
+
+    /**
+     * System prompt for the agent's loop.
+     */
+    systemPrompt?: string;
   }): Promise<PageAgent>;
 
   /**

packages/playwright-core/src/client/page.ts

@@ -858,6 +858,7 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
       maxTokens: options.maxTokens,
       maxTurns: options.maxTurns,
       secrets: options.secrets ? Object.entries(options.secrets).map(([name, value]) => ({ name, value })) : undefined,
+      systemPrompt: options.systemPrompt,
     };
     const { agent } = await this._channel.agent(params);
     return PageAgent.from(agent);

packages/playwright-core/src/protocol/validator.ts

@@ -1491,12 +1491,13 @@ scheme.PageAgentParams = tObject({
   api: tOptional(tString),
   apiKey: tOptional(tString),
   apiEndpoint: tOptional(tString),
-  model: tOptional(tString),
   cacheFile: tOptional(tString),
   cacheOutFile: tOptional(tString),
-  secrets: tOptional(tArray(tType('NameValue'))),
   maxTurns: tOptional(tInt),
   maxTokens: tOptional(tInt),
+  model: tOptional(tString),
+  secrets: tOptional(tArray(tType('NameValue'))),
+  systemPrompt: tOptional(tString),
 });
 scheme.PageAgentResult = tObject({
   agent: tChannel(['PageAgent']),

packages/playwright-core/src/server/agent/pageAgent.ts

@@ -110,16 +110,26 @@ async function runLoop(progress: Progress, context: Context, toolDefinitions: To
     ...context.events,
   });
 
-  const task = `${userTask}
+  const task: string[] = [];
+  if (context.agentParams.systemPrompt) {
+    task.push('### System');
+    task.push(context.agentParams.systemPrompt);
+    task.push('');
+  }
 
-### Context history
-${context.history.map(h => `- ${h.type}: ${h.description}`).join('\n')}
+  task.push('### Task');
+  task.push(userTask);
 
-### Page snapshot
-${full}
-`;
+  if (context.history.length) {
+    task.push('### Context history');
+    task.push(context.history.map(h => `- ${h.type}: ${h.description}`).join('\n'));
+    task.push('');
+  }
+  task.push('### Page snapshot');
+  task.push(full);
+  task.push('');
+  await loop.run(task.join('\n'));
 
-  await loop.run(task);
   return { result: resultSchema ? reportedResult() : undefined };
 }
 

packages/playwright-core/types/types.d.ts

@@ -2143,6 +2143,11 @@ export interface Page {
      * Secrets to hide from the LLM.
      */
     secrets?: { [key: string]: string; };
+
+    /**
+     * System prompt for the agent's loop.
+     */
+    systemPrompt?: string;
   }): Promise<PageAgent>;
 
   /**

packages/protocol/src/channels.d.ts

@@ -2586,23 +2586,25 @@ export type PageAgentParams = {
   api?: string,
   apiKey?: string,
   apiEndpoint?: string,
-  model?: string,
   cacheFile?: string,
   cacheOutFile?: string,
-  secrets?: NameValue[],
   maxTurns?: number,
   maxTokens?: number,
+  model?: string,
+  secrets?: NameValue[],
+  systemPrompt?: string,
 };
 export type PageAgentOptions = {
   api?: string,
   apiKey?: string,
   apiEndpoint?: string,
-  model?: string,
   cacheFile?: string,
   cacheOutFile?: string,
-  secrets?: NameValue[],
   maxTurns?: number,
   maxTokens?: number,
+  model?: string,
+  secrets?: NameValue[],
+  systemPrompt?: string,
 };
 export type PageAgentResult = {
   agent: PageAgentChannel,

packages/protocol/src/protocol.yml

@@ -2019,14 +2019,15 @@ Page:
         api: string?
         apiKey: string?
         apiEndpoint: string?
-        model: string?
         cacheFile: string?
         cacheOutFile: string?
+        maxTurns: int?
+        maxTokens: int?
+        model: string?
         secrets:
           type: array?
           items: NameValue
-        maxTurns: int?
-        maxTokens: int?
+        systemPrompt: string?
       returns:
         agent: PageAgent