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..131821b2c5 --- /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..17854984c1 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 [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. diff --git a/docs/manifest.json b/docs/manifest.json index ea30d8f363..fc915c9403 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,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": [ diff --git a/docs/reference/backend/agent-tasks/create.mdx b/docs/reference/backend/agent-tasks/create.mdx new file mode 100644 index 0000000000..b2222787c8 --- /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/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 +``` + +## `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..e709c50750 --- /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.