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

Start task (streaming)

agent.tasks.start_stream(TaskStartStreamParams**kwargs) -> TaskStartStreamResponse
POST/agent/tasks/stream

Starts an agent task and streams events via SSE (Content-Type: text/event-stream).

ParametersExpand Collapse
instruction: str

Instruction is the task prompt for the agent.

agent_icon: Optional[str]

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: Optional[str]

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

computer_id: Optional[str]

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

context: Optional[Iterable[Context]]

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

content: str

Content is the text of this prior conversation turn.

role: Literal["user", "assistant"]

Role is the speaker for this prior conversation turn.

One of the following:
"user"
"assistant"
environment_id: Optional[str]

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

harness_version: Optional[Literal["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: Optional[str]

IdempotencyKey deduplicates retried task start requests.

maxLength200
minLength1
keep_alive: Optional[bool]

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

kind: Optional[Literal["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: Optional[int]

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

maximum86400
minimum1
max_steps: Optional[int]

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

maximum1000
minimum1
metadata: Optional[Dict[str, str]]

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

model: Optional[str]

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

on_missing_computer: Optional[Literal["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: Optional[bool]

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

save_session: Optional[bool]

SaveSession is a user-friendly alias for Persistent.

screenshot_mode: Optional[Literal["url", "base64"]]

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

One of the following:
"url"
"base64"
start_url: Optional[str]

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

stream_deltas: Optional[bool]

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

stream_mode: Optional[Literal["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: Optional[str]

SystemPrompt is appended to the harness system message.

temperature: Optional[float]

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

maximum2
minimum0
terminate_on_completion: Optional[bool]

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

thread_id: Optional[str]

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: Optional[int]

ViewportHeight is the browser viewport height in pixels.

maximum2160
minimum240
viewport_width: Optional[int]

ViewportWidth is the browser viewport width in pixels.

maximum3840
minimum320
ReturnsExpand Collapse
str

Start task (streaming)

import os
from tzafon import Lightcone

client = Lightcone(
    api_key=os.environ.get("TZAFON_API_KEY"),  # This is the default and can be omitted
)
for task in client.agent.tasks.start_stream(
    instruction="instruction",
):
  print(task)
Returns Examples