Skip to content
Lightcone Lightcone
Try out in chatDeveloper dashboardLogin
API Reference
Agent
Tasks

Start task (async)

client.agent.tasks.start(TaskStartParams { instruction, agent_icon, agent_type, 24 more } body, RequestOptionsoptions?): TaskStartResponse { status, task_id, idempotency_key, reused }
POST/agent/tasks

Starts an agent task and returns a task_id immediately.

ParametersExpand Collapse
body: TaskStartParams { instruction, agent_icon, agent_type, 24 more }
instruction: string

Instruction is the task prompt for the agent.

agent_icon?: string

AgentIcon is optional client metadata used by task history UIs. It is captured by go-backend before proxying and ignored by older agent servers.

agent_type?: string

AgentType is accepted for legacy clients. Current agent servers ignore it.

computer_id?: string

ComputerID reuses a live computer session, or restores a saved persistent session with the same ID if it is not currently live.

context?: Array<Context>

Context seeds the worker transcript with recent conversation turns, oldest first.

content: string

Content is the text of this prior conversation turn.

role: "user" | "assistant"

Role is the speaker for this prior conversation turn.

One of the following:
"user"
"assistant"
environment_id?: string

EnvironmentID restores a previous persistent session snapshot. Prefer ComputerID with the saved computer/session ID for new integrations.

harness_version?: "v1" | "v2"

HarnessVersion selects which agent harness implementation runs the task. "v1" is the stable/core harness with broader shell/search tools. "v2" is the training-aligned GUI harness.

One of the following:
"v1"
"v2"
idempotency_key?: string

IdempotencyKey deduplicates retried task start requests.

maxLength200
minLength1
keep_alive?: boolean

KeepAlive is a user-friendly alias for terminate_on_completion=false.

kind?: "desktop" | "browser"

Kind selects the virtual environment type. Omit to use the agent default: browser when start_url is set, otherwise desktop. Saved computer_id sessions restore using the stored session kind.

One of the following:
"desktop"
"browser"
max_duration_seconds?: number

MaxDurationSeconds caps wall-clock runtime before the server cancels the task.

maximum86400
minimum1
max_steps?: number

MaxSteps caps how many agent loop steps can run before max-steps termination.

maximum1000
minimum1
metadata?: Record<string, string>

Metadata is customer-defined task metadata for correlating with external workflows.

model?: string

Model is the LLM model to use. Omit to use the agent server default.

on_missing_computer?: "fail" | "restore" | "create_new"

OnMissingComputer controls fallback when ComputerID is not live: "restore" (default) restores a saved persistent session or returns 404, "fail" always returns 404, "create_new" restores when possible and otherwise creates a fresh computer.

One of the following:
"fail"
"restore"
"create_new"
persistent?: boolean

Persistent controls whether the computer session should persist state on teardown.

save_session?: boolean

SaveSession is a user-friendly alias for Persistent.

screenshot_mode?: "url" | "base64"

ScreenshotMode controls whether task screenshots are emitted as URLs or base64 data URLs.

One of the following:
"url"
"base64"
start_url?: string

StartURL opens this URL before the agent starts. Omitted kind defaults to browser.

stream_deltas?: boolean

StreamDeltas streams per-token text deltas as progress_update events when supported.

stream_mode?: "verbose" | "concise"

StreamMode controls event verbosity. "verbose" emits all events; "concise" emits product-facing progress, screenshots, completion, and errors.

One of the following:
"verbose"
"concise"
system_prompt?: string

SystemPrompt is appended to the harness system message.

temperature?: number

Temperature controls LLM sampling temperature. Omit to use the harness default.

maximum2
minimum0
terminate_on_completion?: boolean

TerminateOnCompletion controls whether the task should terminate its computer automatically. Set false to keep the computer alive for handoff or inspection.

thread_id?: string

ThreadID is optional client metadata for grouping task history by chat thread. It is captured by go-backend before proxying and ignored by older agent servers.

viewport_height?: number

ViewportHeight is the browser viewport height in pixels.

maximum2160
minimum240
viewport_width?: number

ViewportWidth is the browser viewport width in pixels.

maximum3840
minimum320
ReturnsExpand Collapse
TaskStartResponse { status, task_id, idempotency_key, reused }
status: string
task_id: string
idempotency_key?: string
reused?: boolean

Start task (async)

import Lightcone from '@tzafon/lightcone';

const client = new Lightcone({
  apiKey: process.env['TZAFON_API_KEY'], // This is the default and can be omitted
});

const response = await client.agent.tasks.start({ instruction: 'instruction' });

console.log(response.task_id);
{
  "status": "status",
  "task_id": "task_id",
  "idempotency_key": "idempotency_key",
  "reused": true
}
Returns Examples
{
  "status": "status",
  "task_id": "task_id",
  "idempotency_key": "idempotency_key",
  "reused": true
}