Runs

A run executes an agent on a task. The agent provides the model, skills, guardrails, and tools; the task describes what to do and which resources to work on. The agent runs in a sandbox. Your code receives a Run object for following progress, sending messages, and retrieving results.

Start a run

Retrieve or assemble an agent, then pass a task to agent.run():

import Antigen, { tCell } from "@antigen/sdk";

const antigen = new Antigen(process.env.ANTIGEN_API_KEY);
const agent = await antigen.agents.get(tCell);
const targets = await antigen.getApprovedTargets();

const run = await agent.run({
  instructions: "Test these applications for vulnerabilities.",
  targets,
});

The call returns once the run has started. The agent continues working independently, including if your script exits or disconnects. Each call starts a separate run. Use run.id to identify it:

console.log(run.id);

Define the task

A task contains instructions and the resources the agent should work on.

Field	Purpose
`instructions`	Describe what the agent should do.
`targets`	Approved targets the agent should test.
`vulnerabilities`	Existing vulnerabilities the agent should investigate, remediate, or verify.

The same task can include targets and vulnerabilities. For example, verification instructions can ask an agent to retest a vulnerability against a specific approved target. Task instructions apply to that run. Use skills for procedures and knowledge you want to reuse across runs, and guardrails for constraints on the agent’s behavior.

Work on a vulnerability

Retrieve the vulnerability and include it in the task. This example asks the pre-built remediation-agent to prepare a fix:

import { remediationAgent } from "@antigen/sdk";

const agent = await antigen.agents.get(remediationAgent);
const vulnerability = await antigen.vulnerabilities.get("vuln_abc123");

const run = await agent.run({
  instructions: "Prepare a fix for this vulnerability for our team to review.",
  vulnerabilities: [vulnerability],
});

You can use the same pattern in a webhook handler. When a vulnerability is assigned to your registered agent, retrieve both and start a run with the requested work. See Assigning to your own agents for connecting this to assignment events.

Follow progress

The Run object is an async iterable. Iterate over it to receive events as the agent works:

for await (const event of run) {
  console.log(event.type, event.summary);
}

Events describe activity during the run, such as progress, tool use, and discovered vulnerabilities. If you only need the final results, wait for completion:

await run.wait();

run.wait() resolves when the run completes. If the run fails, it throws an error with the failure details. If the run is stopped, it throws an error indicating that the run was stopped. Vulnerabilities and evidence already saved remain available even if the run fails or stops.

Read vulnerabilities and evidence

Use the run’s resource methods to retrieve vulnerabilities and evidence associated with it:

await run.wait();

const vulnerabilities = await run.vulnerabilities.list();
const evidence = await run.evidence.list();

What a run produces depends on its task. An offensive run may discover vulnerabilities, while a remediation run may prepare a pull request or recommend an infrastructure change. See Vulnerabilities and Evidence for querying and working with these resources.

Adjust or pause the work

Send a message to an active run when you need to provide context or change its focus:

await run.steer("Focus on the GraphQL endpoint we deployed today.");

You can also stop a run and resume it later. See Steering and Stopping and resuming for these controls.

Getting started

Asset Map

Vulnerability Lifecycle

Team Workflows

SDK

CLI

Integrations

Runs

Start a run

Define the task

Work on a vulnerability

Follow progress

Read vulnerabilities and evidence

Adjust or pause the work

​Start a run

​Define the task

​Work on a vulnerability

​Follow progress

​Read vulnerabilities and evidence

​Adjust or pause the work

Start a run

Define the task

Work on a vulnerability

Follow progress

Read vulnerabilities and evidence

Adjust or pause the work