> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antigen.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Human tasks

Use [human tasks](/docs/team-workflows) when an agent needs a person to review a change, grant access, or make a decision.

Each task is assigned to a person and explains what they need to do. Antigen delivers the request through your connected messaging and issue tracking tools, then tracks the response.

| Where your agent runs | How it uses human tasks |
| - | - |
| An agent assembled with the Antigen SDK | Uses the **human\_tasks** tool during its run. |
| Your own service or an external agent environment | Creates and manages tasks through the SDK or Antigen API. |

Both use the same assignments and integrations configured in the platform.

## Use human tasks from an agent

Agents assembled with the SDK have a **human\_tasks** tool they can use to request help and follow the response.

Describe when the agent should involve your team in its [skills](/docs/sdk/skills) or task instructions. For example:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const run = await agent.run({
  instructions: `
    Prepare a fix for this vulnerability.
    If you need access to a repository, create a human task
    for alex@example.com explaining which repository you
    need and what access is required.
  `,
  vulnerabilities: [vulnerability],
});
```

The agent creates the request with the relevant vulnerability context. When the person responds, the agent uses that response to continue its work.

For an access request, it retries the operation after confirmation and follows up if access is still missing.

## Create a task from your code

Call `antigen.humanTasks.create()` with the vulnerability, assignee, and request:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Antigen from "@antigen/sdk";

const antigen = new Antigen(process.env.ANTIGEN_API_KEY);

const task = await antigen.humanTasks.create({
  vulnerabilityId: "vuln_abc123",
  assignee: "alex@example.com",
  title: "Connect the payments repository",
  description: `
    Add acme/payments to the GitHub integration so the
    remediation agent can inspect the affected code.

    Once access is granted, confirm that the repository
    is connected.
  `,
});

console.log(task.id);
```

The assigned person receives a direct message through connected messaging tools and an assigned issue through connected issue trackers. If both are configured, they refer to the same human task.

See [Messaging](/docs/team-workflows/messaging) and [Issue tracking](/docs/team-workflows/issue-tracking) for delivery and assignment behavior.

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `vulnerabilityId` | `string` | Vulnerability the request relates to. |
| `assignee` | `string` | Email address of the person responsible. |
| `title` | `string` | Short description of the requested action. |
| `description` | `string` | What the person needs to do, why it is needed, and how to confirm completion. |
| `completion` | Object | Optional condition that a connected integration can confirm automatically. |

Returns the created task with an `open` status.

## Complete a task automatically

Some actions can be confirmed through a connected integration. For a pull request review, specify the pull request whose merge completes the task:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const task = await antigen.humanTasks.create({
  vulnerabilityId: "vuln_abc123",
  assignee: "alex@example.com",
  title: "Review and merge the authorization fix",
  description: `
    Review the ownership check added to the payments API
    and merge the pull request once the change is approved.
  `,
  completion: {
    type: "pull_request_merged",
    url: "https://github.com/acme/payments/pull/42",
  },
});
```

The task completes when the GitHub integration detects that pull request’s merge. Its associated issue updates automatically.

Without an automatic completion condition, the assigned person completes the action and confirms through the connected tool.

Write each request around the action you need. If the agent needs a fix deployed, the request should ask for deployment confirmation.

## Check a task

Retrieve a task by its ID:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const task = await antigen.humanTasks.get("task_123");

console.log(task.status);
console.log(task.response);
```

| Status | Meaning |
| - | - |
| `open` | The requested action is still outstanding. |
| `completed` | The action was confirmed by a person or a connected integration. |
| `cancelled` | The request is no longer needed. |

`response` contains the person’s completion response when one was provided. Tasks completed through an integration may have no written response.

For an external agent, your service uses the task’s status and response to decide when to continue. A completed access request, for example, tells your service to retry the operation that needed access.

## List tasks

Retrieve tasks associated with a vulnerability:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const tasks = await antigen.humanTasks.list({
  vulnerabilityId: "vuln_abc123",
  status: "open",
});
```

Both filters are optional. Omit them to list tasks across your organization.

Returns an array of tasks. If none match, the array is empty.

## Update a task

Use `antigen.humanTasks.update()` to revise the request or change its assignee:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await antigen.humanTasks.update("task_123", {
  assignee: "sam@example.com",
  description: `
    Connect acme/payments with access to the source code.
    Confirm once the repository is available.
  `,
});
```

Only the supplied fields change. Updates are reflected in the connected tools.

If the request is no longer needed, cancel it:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
await antigen.humanTasks.update("task_123", {
  status: "cancelled",
});
```

## Continue work on the vulnerability

Completing a human task confirms the requested action. The next step depends on what the agent was waiting for: repository access may allow investigation to continue, while deployment confirmation may allow verification to begin.

See [Vulnerabilities](/docs/sdk/vulnerabilities) for updating status and assignment, and [Runs](/docs/sdk/runs) for launching an agent with the vulnerability.