Human tasks

Use human tasks 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 or task instructions. For example:

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:

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 and 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:

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:

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:

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:

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:

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 for updating status and assignment, and Runs for launching an agent with the vulnerability.

Getting started

Asset Map

Runs

Vulnerability Lifecycle

Team Workflows

SDK

CLI

Integrations

Use human tasks from an agent

Create a task from your code

Parameters

Complete a task automatically

Check a task

List tasks

Update a task

Continue work on the vulnerability

​Use human tasks from an agent

​Create a task from your code

​Parameters

​Complete a task automatically

​Check a task

​List tasks

​Update a task

​Continue work on the vulnerability

Use human tasks from an agent

Create a task from your code

Parameters

Complete a task automatically

Check a task

List tasks

Update a task

Continue work on the vulnerability