From e1e664a5252f0edabbee89a05719b75c03782b9d Mon Sep 17 00:00:00 2001 From: Simon Knott Date: Thu, 15 Jan 2026 12:47:52 +0100 Subject: [PATCH 1/2] chore: agent.usage() --- docs/src/api/class-pageagent.md | 16 ++++++++++++++++ packages/playwright-client/types/types.d.ts | 19 +++++++++++++++++++ .../playwright-core/src/client/pageAgent.ts | 5 +++++ .../playwright-core/src/protocol/validator.ts | 4 ++++ .../server/dispatchers/pageAgentDispatcher.ts | 4 ++++ .../src/utils/isomorphic/protocolMetainfo.ts | 3 ++- packages/playwright-core/types/types.d.ts | 19 +++++++++++++++++++ packages/playwright/src/index.ts | 4 ++++ packages/protocol/src/channels.d.ts | 6 ++++++ packages/protocol/src/protocol.yml | 5 +++++ 10 files changed, 84 insertions(+), 1 deletion(-) diff --git a/docs/src/api/class-pageagent.md b/docs/src/api/class-pageagent.md index 4914a8e00b75c..956ea545fabfb 100644 --- a/docs/src/api/class-pageagent.md +++ b/docs/src/api/class-pageagent.md @@ -95,3 +95,19 @@ Task to perform using agentic loop. ### option: PageAgent.perform.-inline- = %%-page-agent-call-options-v1.58-%% * since: v1.58 + +## async method: PageAgent.usage +* since: v1.58 +- returns: <[Object]> + - `turns` <[int]> + - `inputTokens` <[int]> + - `outputTokens` <[int]> + +Returns the current token usage for this agent. + +**Usage** + +```js +const usage = await agent.usage(); +console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`); +``` diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts index 1dfa0737ade3e..a9d3c3daff9fa 100644 --- a/packages/playwright-client/types/types.d.ts +++ b/packages/playwright-client/types/types.d.ts @@ -5462,6 +5462,25 @@ export interface PageAgent { }; }>; + /** + * Returns the current token usage for this agent. + * + * **Usage** + * + * ```js + * const usage = await agent.usage(); + * console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`); + * ``` + * + */ + usage(): Promise<{ + turns: number; + + inputTokens: number; + + outputTokens: number; + }>; + [Symbol.asyncDispose](): Promise; } diff --git a/packages/playwright-core/src/client/pageAgent.ts b/packages/playwright-core/src/client/pageAgent.ts index 7b3998a9e86ba..10d64a9c72f0c 100644 --- a/packages/playwright-core/src/client/pageAgent.ts +++ b/packages/playwright-core/src/client/pageAgent.ts @@ -56,6 +56,11 @@ export class PageAgent extends ChannelOwner implement return { result, usage }; } + async usage() { + const { usage } = await this._channel.usage({}); + return usage; + } + async dispose() { await this._channel.dispose(); } diff --git a/packages/playwright-core/src/protocol/validator.ts b/packages/playwright-core/src/protocol/validator.ts index 2f9161ad5196c..62dca989ba68a 100644 --- a/packages/playwright-core/src/protocol/validator.ts +++ b/packages/playwright-core/src/protocol/validator.ts @@ -2939,6 +2939,10 @@ scheme.PageAgentExtractResult = tObject({ }); scheme.PageAgentDisposeParams = tOptional(tObject({})); scheme.PageAgentDisposeResult = tOptional(tObject({})); +scheme.PageAgentUsageParams = tOptional(tObject({})); +scheme.PageAgentUsageResult = tObject({ + usage: tType('AgentUsage'), +}); scheme.AgentUsage = tObject({ turns: tInt, inputTokens: tInt, diff --git a/packages/playwright-core/src/server/dispatchers/pageAgentDispatcher.ts b/packages/playwright-core/src/server/dispatchers/pageAgentDispatcher.ts index d830d65dafadd..c30f551085b4d 100644 --- a/packages/playwright-core/src/server/dispatchers/pageAgentDispatcher.ts +++ b/packages/playwright-core/src/server/dispatchers/pageAgentDispatcher.ts @@ -62,6 +62,10 @@ export class PageAgentDispatcher extends Dispatcher { + return { usage: this._usage }; + } + async dispose(params: channels.PageAgentDisposeParams, progress: Progress): Promise { } diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts index 616b5e838b092..20017908e1e3b 100644 --- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts +++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts @@ -316,5 +316,6 @@ export const methodMetainfo = new Map; + /** + * Returns the current token usage for this agent. + * + * **Usage** + * + * ```js + * const usage = await agent.usage(); + * console.log(`Tokens used: ${usage.inputTokens} in, ${usage.outputTokens} out`); + * ``` + * + */ + usage(): Promise<{ + turns: number; + + inputTokens: number; + + outputTokens: number; + }>; + [Symbol.asyncDispose](): Promise; } diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.ts index 90c942f28c3dd..1a52a43897417 100644 --- a/packages/playwright/src/index.ts +++ b/packages/playwright/src/index.ts @@ -486,6 +486,10 @@ const playwrightFixtures: Fixtures = ({ await use(agent); + const usage = await agent.usage(); + if (usage.turns > 0) + await testInfoImpl.attach('agent-usage', { contentType: 'application/json', body: Buffer.from(JSON.stringify(usage, null, 2)) }); + if (!resolvedCacheFile || !cacheOutFile) return; if (testInfo.status !== 'passed') diff --git a/packages/protocol/src/channels.d.ts b/packages/protocol/src/channels.d.ts index 600a3ab63edb5..38e0009d0d806 100644 --- a/packages/protocol/src/channels.d.ts +++ b/packages/protocol/src/channels.d.ts @@ -5103,6 +5103,7 @@ export interface PageAgentChannel extends PageAgentEventTarget, EventTargetChann expect(params: PageAgentExpectParams, progress?: Progress): Promise; extract(params: PageAgentExtractParams, progress?: Progress): Promise; dispose(params?: PageAgentDisposeParams, progress?: Progress): Promise; + usage(params?: PageAgentUsageParams, progress?: Progress): Promise; } export type PageAgentTurnEvent = { role: string, @@ -5165,6 +5166,11 @@ export type PageAgentExtractResult = { export type PageAgentDisposeParams = {}; export type PageAgentDisposeOptions = {}; export type PageAgentDisposeResult = void; +export type PageAgentUsageParams = {}; +export type PageAgentUsageOptions = {}; +export type PageAgentUsageResult = { + usage: AgentUsage, +}; export interface PageAgentEvents { 'turn': PageAgentTurnEvent; diff --git a/packages/protocol/src/protocol.yml b/packages/protocol/src/protocol.yml index 0d11c2d567b6d..37f7d5131980f 100644 --- a/packages/protocol/src/protocol.yml +++ b/packages/protocol/src/protocol.yml @@ -4352,6 +4352,11 @@ PageAgent: dispose: internal: true + usage: + title: 'Get agent usage' + returns: + usage: AgentUsage + events: turn: From 88f85f1f4a5902946083d4a5346f060b391a5fc1 Mon Sep 17 00:00:00 2001 From: Simon Knott Date: Thu, 15 Jan 2026 14:36:14 +0100 Subject: [PATCH 2/2] add group --- .../playwright-core/src/utils/isomorphic/protocolMetainfo.ts | 2 +- packages/protocol/src/protocol.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts index 20017908e1e3b..4da75fa607c63 100644 --- a/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts +++ b/packages/playwright-core/src/utils/isomorphic/protocolMetainfo.ts @@ -317,5 +317,5 @@ export const methodMetainfo = new Map