Agent Tasks

Create agent task

Changed on

Create an agent task on behalf of a user. The response contains a URL that, when visited, creates a session for the user. The agent_id is stable per agent_name within an instance. The agent_task_id is unique per call.

post/agents/tasks

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/agents/tasks
  • Auth: HTTP bearer

Request body

permissions'*' required

The permissions granted to the agent task. Must be "*" (all permissions).

agent_namestring required

A name identifying the agent. Used to derive a stable agent_id per instance. Logged for audit purposes.

task_descriptionstring required

A description of the task being performed. Logged for audit purposes.

redirect_urlstring uri required

The URL the user is redirected to after the agent task is accepted. Must be a valid absolute URL with an https scheme in production instances. In development instances, http is also permitted. The URL's domain must belong to one of the instance's associated domains (primary or satellite); otherwise the redirect will be rejected when the task ticket is consumed.

session_max_duration_in_secondsinteger

The maximum duration that the session which will be created by the generated agent task should last. By default, the duration of a session created via an agent task lasts 30 minutes.

Response

Success

object'agent_task' required
agent_idstring required

A stable identifier for the agent, unique per agent_name within an instance.

agent_task_idstring required

A unique identifier for this agent task.

task_idstring required

A unique identifier for this agent task. Deprecated: use agent_task_id instead.

urlstring

The URL that, when visited, creates a session for the user. Only present in the response to a create request.

Changes