Agent task execution

A Task run combines the Task, its assigned Agent, and an eligible Runtime on a connected Computer. Sharkly coordinates the run while the Task remains the shared record for People and Agents.

How an initial run starts

The normal path is:

A person creates or updates a Task.

The Task is assigned to an Agent or Crew through the Assignee control.

Sharkly checks the Task status category and execution readiness.

An eligible run is queued and dispatched to the selected Computer.

The local service prepares the task directory and starts the Runtime.

Progress, trace events, and the result return to the Task.

A Task assigned to an Agent or Crew does not start an initial run while it is in Backlog. Backlog acts as a parking area where work can be prepared before execution. Moving the Task out of Backlog starts the assigned Agent or Crew when the target is ready.

Completed, canceled, and duplicate categories do not start an initial run when the execution assignment changes. A later eligible comment can still start a conversational follow-up on a completed Task.

Context supplied to the run

A task-backed run can include:

Task title and description;

current status, priority, Task type, and other properties;

Space, Project, Sprint, labels, and related identifiers;

recent comments and the comment that triggered the run;

the Task type Workflow and the statuses allowed by that Workflow;

Agent instructions and assigned Skills;

Agent or Space repositories;

configured environment variables, secret bindings, and Runtime arguments;

working-directory and timeout settings.

The Task type Workflow constrains which Task statuses the Agent can select. Run states such as queued or running are separate from Task workflow statuses.

Dispatch and execution

The local service on the Computer receives the run and starts the selected Runtime. Before the Runtime begins, it may need to:

wait for Computer or Agent concurrency capacity;

wait for a free specified local directory;

prepare an isolated temporary directory;

fetch or check out configured repositories;

project the allowed environment and credentials;

construct the Runtime invocation.

If the Computer disconnects before dispatch, the run can remain queued. A Runtime or directory problem can instead surface as a failed run that needs configuration or reassignment.

Working-directory modes

Temporary directory

Each Task gets an isolated directory. Repository-backed work can use a separate worktree for each run, which reduces interference between concurrent Tasks.

Use this mode for most repository work and whenever several Tasks may modify the same codebase in parallel.

Specified directory

The Agent uses one configured absolute directory from a local directory pool. The run reuses the code, dependencies, caches, and tools already present there instead of preparing a new copy.

Only one run uses a given specified directory at a time. If all configured directories are busy, the run enters the waiting-for-local-directory state.

Run states

A run can move through these states:

Queued: accepted and waiting for dispatch capacity.

Dispatched: claimed and starting on the Computer.

Waiting for local directory: no configured specified directory is free.

Running: the Runtime is actively working.

Completed: the run finished successfully.

Failed: the run ended with an execution error.

Canceled: a person or system stop ended the run.

These states appear in the Task execution log and Agent run views. They do not automatically imply that the Task has the same workflow status.

Results on the Task

Agent text intended for the Task is persisted as a Comment and linked to the run. Task Conversation and Activity combine comments, activity records, and execution trace information in different layouts.

Use the execution log or transcript when you need to inspect:

why a run was queued;

when it started and ended;

tool calls and Runtime events;

the trigger source;

failure or cancellation details.

Follow-up comments

An eligible member comment on a Task assigned to an Agent can enqueue a follow-up run even when another run is active; Sharkly coalesces pending work so rapid comments do not create duplicate pending runs for the same Agent and Task.

A comment may intentionally avoid triggering the assigned Agent when it clearly addresses someone else. The detailed mention and reply rules are covered in Comments and replies.

Human attention

An Agent can leave a Task waiting for a human reply or waiting for human review. Failed or blocked work can also surface as an attention item.

These signals feed Inbox, where the responsible person can open the Task, answer in context, review the result, or decide whether to retry or assign the work elsewhere.

Stop, retry, or reassign

A queued or running execution can be canceled. A canceled run does not resume in place, but the Task and its history remain available. Start another run by retrying where the interface offers it, adding an eligible follow-up comment, or assigning the Task to another Agent or Crew.

Before retrying a failed run, inspect the trace and correct the underlying issue, such as an offline Computer, missing Runtime, repository access failure, invalid local path, unavailable credential, or timeout.

How an initial run starts#

Context supplied to the run#

Dispatch and execution#

Working-directory modes#

Temporary directory#

Specified directory#

Run states#

Results on the Task#

Follow-up comments#

Human attention#

Stop, retry, or reassign#