feat: Agent Tasks

.gitignore

@@ -42,6 +42,7 @@ yarn.lock
 
 .idea/
 .context/
+.claude/settings.local.json
 
 /docs/docs
 /docs/docs/

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')
+```

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 [Agent Tasks guide](/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.

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,23 @@
                             ]
                           ]
                         },
+                        {
+                          "title": "Agent Tasks",
+                          "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": [

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/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<AgentTask>
+```
+
+## `CreateAgentTaskParams`
+
+<Properties>
+  - `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).
+</Properties>
+
+## `AgentTask`
+
+`create()` returns an `AgentTask` object with the following properties:
+
+<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.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```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)
+```

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<Omit<AgentTask, 'url'>>
+```
+
+## Parameters
+
+<Properties>
+  - `agentTaskId`
+  - `string`
+
+  The ID of the agent task to revoke.
+</Properties>
+
+## Example
+
+<Include src="_partials/backend/usage" />
+
+```tsx
+await clerk.agentTasks.revoke('agtask_xxx')
+```

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.