---
title: "Create agent task"
method: POST
path: "/agents/tasks"
tags: ["Agent Tasks"]
---

# Create agent task

`POST /agents/tasks`

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.

## Request body

- object
  - `on_behalf_of` object, required — Identifies the user on whose behalf the agent task is created. Exactly one of user_id or identifier must be provided.
    - `user_id` string — The ID of the user.
    - `identifier` string — A verified identifier (e.g. email address) belonging to the user.
  - `permissions` '*', required — The permissions granted to the agent task. Must be "*" (all permissions).
  - `agent_name` string, required — A name identifying the agent. Used to derive a stable agent_id per instance. Logged for audit purposes.
  - `task_description` string, required — A description of the task being performed. Logged for audit purposes.
  - `redirect_url` string, 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_seconds` integer — 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 `200`

Success

- AgentTask
  - `object` 'agent_task', required
  - `agent_id` string, required — A stable identifier for the agent, unique per agent_name within an instance.
  - `agent_task_id` string, required — A unique identifier for this agent task.
  - `task_id` string, required — A unique identifier for this agent task. Deprecated: use agent_task_id instead.
  - `url` string — The URL that, when visited, creates a session for the user. Only present in the response to a create request.

## Other responses

- `400` — Request was not successful
- `404` — Resource not found
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/7d969765e49a/schema)