From 9a56334a470699b570de4151abadd8338e8bf77d Mon Sep 17 00:00:00 2001 From: Tom Milewski Date: Wed, 4 Mar 2026 13:59:51 -0500 Subject: [PATCH 1/8] feat: Agent Tasks --- .gitignore | 1 + .../development/testing/agent-tasks.mdx | 74 ++++++++++++++ docs/guides/development/testing/overview.mdx | 4 + docs/manifest.json | 22 +++++ docs/reference/backend/agent-tasks/create.mdx | 98 +++++++++++++++++++ docs/reference/backend/agent-tasks/revoke.mdx | 28 ++++++ docs/reference/backend/overview.mdx | 4 + 7 files changed, 231 insertions(+) create mode 100644 docs/guides/development/testing/agent-tasks.mdx create mode 100644 docs/reference/backend/agent-tasks/create.mdx create mode 100644 docs/reference/backend/agent-tasks/revoke.mdx diff --git a/.gitignore b/.gitignore index 9a2d1db393..80a93c6656 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ yarn.lock .idea/ .context/ +.claude/settings.local.json /docs/docs /docs/docs/ diff --git a/docs/guides/development/testing/agent-tasks.mdx b/docs/guides/development/testing/agent-tasks.mdx new file mode 100644 index 0000000000..c7401d01ce --- /dev/null +++ b/docs/guides/development/testing/agent-tasks.mdx @@ -0,0 +1,74 @@ +--- +title: Agent Tasks +description: Use Agent Tasks to create authenticated sessions on behalf of users in your tests and AI agent workflows. +--- + +Agent Tasks provide a way to create authenticated sessions on behalf of users without going through the standard sign-in flow. When you create an agent task, Clerk returns a URL that, when visited, creates a session for the specified user and redirects to the URL of your choice. + +This is useful for: + +- Automated end-to-end testing where you need a signed-in user +- AI agent workflows that act on behalf of a user + +## Create an agent task + +Use the [Backend SDK](/docs/reference/backend/agent-tasks/create) to create an agent task. The returned `url` can then be visited to establish the session. + +```ts +import { createClerkClient } from '@clerk/backend' + +const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY +}) + +const agentTask = await clerkClient.agentTasks.create({ + onBehalfOf: { + userId: 'user_xxx', + // or { identifier: 'test@example.com' } + }, + permissions: '*', + agentName: 'my-agent', + taskDescription: 'Automated test login', + redirectUrl: 'http://localhost:3000/dashboard', +}) + +// Visit this URL to create a session for the user +console.log(agentTask.url) +``` + +## Use with Playwright + +The following example shows how to use an agent task in a Playwright test to authenticate a user. + +```ts {{ filename: 'e2e/app.spec.ts' }} +import { createClerkClient } from '@clerk/backend' +import { test, expect } from '@playwright/test' + +const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY +}) + +test('authenticated user flow', async ({ page }) => { + const agentTask = await clerkClient.agentTasks.create({ + onBehalfOf: { + userId: 'user_xxx', + // or { identifier: 'test@example.com' } + }, + permissions: '*', + agentName: 'test-agent', + taskDescription: 'test-login', + redirectUrl: 'http://localhost:3000/dashboard', + }) + + await page.goto(agentTask.url) + await expect(page.locator('header')).toContainText('Welcome') +}) +``` + +## Revoke an agent task + +If you need to invalidate an agent task before it's used, you can [revoke it](/docs/reference/backend/agent-tasks/revoke). + +```ts +await clerkClient.agentTasks.revoke('agtask_xxx') +``` diff --git a/docs/guides/development/testing/overview.mdx b/docs/guides/development/testing/overview.mdx index 2670eb581f..6ed59d4ef7 100644 --- a/docs/guides/development/testing/overview.mdx +++ b/docs/guides/development/testing/overview.mdx @@ -24,6 +24,10 @@ If the session token expires, you will need to refresh it with the same [create For more information, feedback or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package. +## Agent Tasks + +Agent Tasks allow you to create authenticated sessions on behalf of users without going through the standard sign-in flow. This is useful for automated end-to-end testing and AI agent workflows. Read the complete documentation [here](/docs/guides/development/testing/agent-tasks). + ## Testing Tokens Testing Tokens allow you to bypass bot detection mechanisms that protect Clerk applications from malicious bots, ensuring your test suites run smoothly. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests. diff --git a/docs/manifest.json b/docs/manifest.json index ea30d8f363..55a4ba1858 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1416,6 +1416,10 @@ "title": "Test emails and phones", "href": "/docs/guides/development/testing/test-emails-and-phones" }, + { + "title": "Agent Tasks", + "href": "/docs/guides/development/testing/agent-tasks" + }, { "title": "Cypress", "items": [ @@ -2894,6 +2898,24 @@ ] ] }, + { + "title": "Agent Tasks", + "tag": "(Beta)", + "items": [ + [ + { + "title": "`create()`", + "wrap": false, + "href": "/docs/reference/backend/agent-tasks/create" + }, + { + "title": "`revoke()`", + "wrap": false, + "href": "/docs/reference/backend/agent-tasks/revoke" + } + ] + ] + }, { "title": "Testing Tokens", "items": [ diff --git a/docs/reference/backend/agent-tasks/create.mdx b/docs/reference/backend/agent-tasks/create.mdx new file mode 100644 index 0000000000..3b9d027c19 --- /dev/null +++ b/docs/reference/backend/agent-tasks/create.mdx @@ -0,0 +1,98 @@ +--- +title: '`create()`' +description: Use Clerk's JS Backend SDK to create an agent task. +sdk: js-backend +--- + +Creates an [agent task](/docs/guides/ai/overview) that generates a URL which, when visited, creates a session for the specified user. This is useful for automated testing or agent-driven flows where full authentication isn't practical. + +```ts +function create(params: CreateAgentTaskParams): Promise +``` + +## `CreateAgentTaskParams` + + + - `onBehalfOf` + - `{ userId: string } | { identifier: string }` + + The user to create the agent task for. Provide either a `userId` or an `identifier` (e.g., an email address). + + --- + + - `permissions` + - `string` + + The permissions the agent task will have. Use `'*'` to grant all permissions. + + --- + + - `agentName` + - `string` + + The name of the agent creating the task. + + --- + + - `taskDescription` + - `string` + + A description of the agent task. + + --- + + - `redirectUrl` + - `string` + + The URL to redirect to after the agent task is consumed. + + --- + + - `sessionMaxDurationInSeconds?` + - `number` + + The maximum duration in seconds for the session created by the agent task. Defaults to 30 minutes (1800 seconds). + + +## `AgentTask` + +`create()` returns an `AgentTask` object with the following properties: + + + - `agentId` + - `string` + + A stable identifier for the agent, unique per `agentName` within an instance. + + --- + + - `taskId` + - `string` + + A unique identifier for this agent task. + + --- + + - `url` + - `string` + + The URL that, when visited, creates a session for the user. + + +## Example + + + +```tsx +const agentTask = await clerk.agentTasks.create({ + onBehalfOf: { + userId: 'user_xxx', + }, + permissions: '*', + agentName: 'my-agent', + taskDescription: 'Perform automated action', + redirectUrl: 'https://example.com/dashboard', +}) + +console.log(agentTask.url) +``` diff --git a/docs/reference/backend/agent-tasks/revoke.mdx b/docs/reference/backend/agent-tasks/revoke.mdx new file mode 100644 index 0000000000..2cefa34ce4 --- /dev/null +++ b/docs/reference/backend/agent-tasks/revoke.mdx @@ -0,0 +1,28 @@ +--- +title: '`revoke()`' +description: Use Clerk's JS Backend SDK to revoke an agent task. +sdk: js-backend +--- + +Revokes an existing agent task, preventing it from being used to create a session. + +```ts +function revoke(agentTaskId: string): Promise +``` + +## Parameters + + + - `agentTaskId` + - `string` + + The ID of the agent task to revoke. + + +## Example + + + +```tsx +await clerk.agentTasks.revoke('agtask_xxx') +``` diff --git a/docs/reference/backend/overview.mdx b/docs/reference/backend/overview.mdx index b9c26f4aed..e9fe58c77e 100644 --- a/docs/reference/backend/overview.mdx +++ b/docs/reference/backend/overview.mdx @@ -79,6 +79,10 @@ The **SAML Connection** resource allows you to manage SAML connections associate The **Sign-in Token** resource allows you to create and manage sign-in tokens for your application. Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials. A sign-in token can be used at most once and can be consumed from the Frontend API using the `ticket` strategy. +### Agent tasks + +The **Agent Task** resource allows you to create agent tasks that generate URLs for creating sessions on behalf of users. This is useful for automated testing or agent-driven flows where full authentication isn't practical. The `create()` operation returns an `AgentTask` object containing a `url` that, when visited, creates a session for the specified user. + ### Testing tokens The **Testing Token** resource allows you to create and manage [testing tokens](/docs/guides/development/testing/overview#testing-tokens) for your application. Testing tokens allow you to bypass bot detection mechanisms that protect Clerk applications from malicious bots, ensuring your end-to-end test suites run smoothly. Without Testing tokens, you may encounter "Bot traffic detected" errors in your requests. From 0a298a3105bd72ca072b69657bfbd2a85c37d343 Mon Sep 17 00:00:00 2001 From: Tom Milewski Date: Wed, 4 Mar 2026 14:03:05 -0500 Subject: [PATCH 2/8] chore: Remove beta tag --- docs/manifest.json | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/manifest.json b/docs/manifest.json index 55a4ba1858..fc915c9403 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2900,7 +2900,6 @@ }, { "title": "Agent Tasks", - "tag": "(Beta)", "items": [ [ { From f5c064950a12856ad961b30196a677028f15d873 Mon Sep 17 00:00:00 2001 From: Tom Milewski Date: Wed, 4 Mar 2026 14:23:11 -0500 Subject: [PATCH 3/8] fix: linting --- docs/guides/development/testing/agent-tasks.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/development/testing/agent-tasks.mdx b/docs/guides/development/testing/agent-tasks.mdx index c7401d01ce..131821b2c5 100644 --- a/docs/guides/development/testing/agent-tasks.mdx +++ b/docs/guides/development/testing/agent-tasks.mdx @@ -17,13 +17,13 @@ Use the [Backend SDK](/docs/reference/backend/agent-tasks/create) to create an a ```ts import { createClerkClient } from '@clerk/backend' -const clerkClient = createClerkClient({ - secretKey: process.env.CLERK_SECRET_KEY +const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY, }) const agentTask = await clerkClient.agentTasks.create({ onBehalfOf: { - userId: 'user_xxx', + userId: 'user_xxx', // or { identifier: 'test@example.com' } }, permissions: '*', @@ -44,14 +44,14 @@ The following example shows how to use an agent task in a Playwright test to aut import { createClerkClient } from '@clerk/backend' import { test, expect } from '@playwright/test' -const clerkClient = createClerkClient({ - secretKey: process.env.CLERK_SECRET_KEY +const clerkClient = createClerkClient({ + secretKey: process.env.CLERK_SECRET_KEY, }) test('authenticated user flow', async ({ page }) => { const agentTask = await clerkClient.agentTasks.create({ onBehalfOf: { - userId: 'user_xxx', + userId: 'user_xxx', // or { identifier: 'test@example.com' } }, permissions: '*', From 44bbf5c7a50b4858a33fe7bfd4fb5702faad7f06 Mon Sep 17 00:00:00 2001 From: Tom Milewski Date: Fri, 6 Mar 2026 11:25:00 -0500 Subject: [PATCH 4/8] Update docs/reference/backend/agent-tasks/revoke.mdx Co-authored-by: Michael Novotny --- docs/reference/backend/agent-tasks/revoke.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/backend/agent-tasks/revoke.mdx b/docs/reference/backend/agent-tasks/revoke.mdx index 2cefa34ce4..e709c50750 100644 --- a/docs/reference/backend/agent-tasks/revoke.mdx +++ b/docs/reference/backend/agent-tasks/revoke.mdx @@ -7,7 +7,7 @@ sdk: js-backend Revokes an existing agent task, preventing it from being used to create a session. ```ts -function revoke(agentTaskId: string): Promise +function revoke(agentTaskId: string): Promise> ``` ## Parameters From 045a53ec8b29ef3752c0079ca8a988364c63bf00 Mon Sep 17 00:00:00 2001 From: Tom Milewski Date: Fri, 6 Mar 2026 11:25:24 -0500 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Michael Novotny --- docs/guides/development/testing/overview.mdx | 2 +- docs/reference/backend/agent-tasks/create.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/development/testing/overview.mdx b/docs/guides/development/testing/overview.mdx index 6ed59d4ef7..17854984c1 100644 --- a/docs/guides/development/testing/overview.mdx +++ b/docs/guides/development/testing/overview.mdx @@ -26,7 +26,7 @@ For more information, feedback or issues, visit the [`@clerk/testing`](https://g ## Agent Tasks -Agent Tasks allow you to create authenticated sessions on behalf of users without going through the standard sign-in flow. This is useful for automated end-to-end testing and AI agent workflows. Read the complete documentation [here](/docs/guides/development/testing/agent-tasks). +Agent Tasks allow you to create authenticated sessions on behalf of users without going through the standard sign-in flow. This is useful for automated end-to-end testing and AI agent workflows. Read the complete [Agent Tasks guide](/docs/guides/development/testing/agent-tasks). ## Testing Tokens diff --git a/docs/reference/backend/agent-tasks/create.mdx b/docs/reference/backend/agent-tasks/create.mdx index 3b9d027c19..b2222787c8 100644 --- a/docs/reference/backend/agent-tasks/create.mdx +++ b/docs/reference/backend/agent-tasks/create.mdx @@ -4,7 +4,7 @@ description: Use Clerk's JS Backend SDK to create an agent task. sdk: js-backend --- -Creates an [agent task](/docs/guides/ai/overview) that generates a URL which, when visited, creates a session for the specified user. This is useful for automated testing or agent-driven flows where full authentication isn't practical. +Creates an [agent task](/docs/guides/development/testing/agent-tasks) that generates a URL which, when visited, creates a session for the specified user. This is useful for automated testing or agent-driven flows where full authentication isn't practical. ```ts function create(params: CreateAgentTaskParams): Promise From 020862d802a60873360cbfc44a9279aa2c6080a2 Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Tue, 19 May 2026 10:49:14 -0500 Subject: [PATCH 6/8] Apply review feedback Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/ai/overview.mdx | 4 ++++ docs/guides/development/testing/agent-tasks.mdx | 5 +---- docs/reference/backend/agent-tasks/create.mdx | 12 +++++++----- docs/reference/backend/agent-tasks/revoke.mdx | 6 +++++- 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/guides/ai/overview.mdx b/docs/guides/ai/overview.mdx index a5a2b499e5..57a29b2495 100644 --- a/docs/guides/ai/overview.mdx +++ b/docs/guides/ai/overview.mdx @@ -33,6 +33,10 @@ To learn how to implement both sides of the flow using Clerk, refer to the follo - [Build an MCP server](/docs/guides/ai/mcp/build-mcp-server) - [Connect an MCP client](/docs/guides/ai/mcp/connect-mcp-client) +## Agent Tasks + +Agent Tasks allow you to create authenticated sessions on behalf of users without going through the standard sign-in flow. This is useful for AI agent workflows where an agent needs to act on behalf of a user. Read the complete [Agent Tasks guide](/docs/guides/development/testing/agent-tasks). + ## AI prompts Clerk's AI prompt library provides curated prompts to help you work more efficiently with AI-powered development tools like Cursor, Claude Code, Codex, GitHub Copilot, and more. These prompts guide AI assistants in helping you implement Clerk's features correctly. diff --git a/docs/guides/development/testing/agent-tasks.mdx b/docs/guides/development/testing/agent-tasks.mdx index 131821b2c5..41984b7165 100644 --- a/docs/guides/development/testing/agent-tasks.mdx +++ b/docs/guides/development/testing/agent-tasks.mdx @@ -31,9 +31,6 @@ const agentTask = await clerkClient.agentTasks.create({ taskDescription: 'Automated test login', redirectUrl: 'http://localhost:3000/dashboard', }) - -// Visit this URL to create a session for the user -console.log(agentTask.url) ``` ## Use with Playwright @@ -70,5 +67,5 @@ test('authenticated user flow', async ({ page }) => { If you need to invalidate an agent task before it's used, you can [revoke it](/docs/reference/backend/agent-tasks/revoke). ```ts -await clerkClient.agentTasks.revoke('agtask_xxx') +await clerkClient.agentTasks.revoke('agttsk_xxx') ``` diff --git a/docs/reference/backend/agent-tasks/create.mdx b/docs/reference/backend/agent-tasks/create.mdx index b2222787c8..a8344681b4 100644 --- a/docs/reference/backend/agent-tasks/create.mdx +++ b/docs/reference/backend/agent-tasks/create.mdx @@ -23,7 +23,7 @@ function create(params: CreateAgentTaskParams): Promise - `permissions` - `string` - The permissions the agent task will have. Use `'*'` to grant all permissions. + The permissions the agent task will have. Currently, `'*'` is the only supported value, which grants all permissions. --- @@ -66,7 +66,7 @@ function create(params: CreateAgentTaskParams): Promise --- - - `taskId` + - `agentTaskId` - `string` A unique identifier for this agent task. @@ -84,7 +84,7 @@ function create(params: CreateAgentTaskParams): Promise ```tsx -const agentTask = await clerk.agentTasks.create({ +const agentTask = await clerkClient.agentTasks.create({ onBehalfOf: { userId: 'user_xxx', }, @@ -93,6 +93,8 @@ const agentTask = await clerk.agentTasks.create({ taskDescription: 'Perform automated action', redirectUrl: 'https://example.com/dashboard', }) - -console.log(agentTask.url) ``` + +## Backend API (BAPI) endpoint + +This method in the SDK is a wrapper around the BAPI endpoint `POST/agents/tasks`. See the [BAPI reference](/docs/reference/backend-api/tag/agent-tasks){{ target: '_blank' }} for more information. diff --git a/docs/reference/backend/agent-tasks/revoke.mdx b/docs/reference/backend/agent-tasks/revoke.mdx index e709c50750..732ba9fc54 100644 --- a/docs/reference/backend/agent-tasks/revoke.mdx +++ b/docs/reference/backend/agent-tasks/revoke.mdx @@ -24,5 +24,9 @@ function revoke(agentTaskId: string): Promise> ```tsx -await clerk.agentTasks.revoke('agtask_xxx') +await clerkClient.agentTasks.revoke('agttsk_xxx') ``` + +## Backend API (BAPI) endpoint + +This method in the SDK is a wrapper around the BAPI endpoint `POST/agents/tasks/{agent_task_id}/revoke`. See the [BAPI reference](/docs/reference/backend-api/tag/agent-tasks/POST/agents/tasks/%7Bagent_task_id%7D/revoke){{ target: '_blank' }} for more information. From f534a3fd6f8288560f32b3119c5b597f734d50dd Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Tue, 19 May 2026 11:22:26 -0500 Subject: [PATCH 7/8] Restore beta tag Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/manifest.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/manifest.json b/docs/manifest.json index fc915c9403..55a4ba1858 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2900,6 +2900,7 @@ }, { "title": "Agent Tasks", + "tag": "(Beta)", "items": [ [ { From 54c27d754e392d949d62a85a4d044c47cc95e71d Mon Sep 17 00:00:00 2001 From: Michael Novotny Date: Tue, 19 May 2026 11:25:28 -0500 Subject: [PATCH 8/8] Surface agentTask.url in create examples Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/guides/development/testing/agent-tasks.mdx | 2 ++ docs/reference/backend/agent-tasks/create.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/guides/development/testing/agent-tasks.mdx b/docs/guides/development/testing/agent-tasks.mdx index 41984b7165..74adff28b8 100644 --- a/docs/guides/development/testing/agent-tasks.mdx +++ b/docs/guides/development/testing/agent-tasks.mdx @@ -31,6 +31,8 @@ const agentTask = await clerkClient.agentTasks.create({ taskDescription: 'Automated test login', redirectUrl: 'http://localhost:3000/dashboard', }) + +// agentTask.url is the URL to visit to authenticate the user ``` ## Use with Playwright diff --git a/docs/reference/backend/agent-tasks/create.mdx b/docs/reference/backend/agent-tasks/create.mdx index a8344681b4..8705b8ecac 100644 --- a/docs/reference/backend/agent-tasks/create.mdx +++ b/docs/reference/backend/agent-tasks/create.mdx @@ -93,6 +93,8 @@ const agentTask = await clerkClient.agentTasks.create({ taskDescription: 'Perform automated action', redirectUrl: 'https://example.com/dashboard', }) + +// agentTask.url is the URL to visit to authenticate the user ``` ## Backend API (BAPI) endpoint