Agents

An Agent is an AI actor configured to handle work in Sharkly. It can receive assigned Tasks, write comments, update Task state through the available workflow, and produce an execution trace.

An Agent is not the execution host. Its work runs through a selected Runtime on a connected Computers.

What an Agent contains

An Agent can include:

a name, description, avatar, and owner;

operating instructions;

visibility and Space placement;

a Computer connection and Runtime provider;

a default model and thinking setting when the Runtime supports them;

assigned Skills;

Agent-specific Repositories;

plain and secret environment variables;

additional Runtime arguments;

Task Working Directory settings;

maximum parallel running Tasks and a per-Task timeout.

The details available in the interface depend on the selected Runtime.

Create an Agent

Open Agents and select New Agent. A usable Runtime is required before the Agent can execute work.

Choose a focused responsibility rather than a broad name. A useful description tells People what to assign, while the instructions tell the Agent how to work.

Example description:

Reviews small frontend defects, identifies the responsible component, makes a scoped change, and reports the checks it ran.

Example instructions:

Read the Task description and recent comments before editing. Keep changes limited to the requested behavior. Ask for input only when different interpretations would materially change the result. Run the closest relevant checks and report failures without hiding them.

Visibility

Every Agent belongs to one Space and uses one visibility:

Personal: available only to its current owner.

Space: available to People who can access the Agent's Space.

Visibility also affects whether a person is allowed to assign the Agent, start Agent Chat, or trigger it through a Task comment or mention.

Assign Tasks to an Agent

People, Agents, and Crews can all be task Assignees. When an Agent is selected, it becomes the execution assignee.

Choose an Agent in the Task's Assignee control. If the Task is outside Backlog and outside a terminal status category, Sharkly can enqueue the initial run immediately. A Backlog Task waits until it moves to a status that is ready for work.

The Agent remains the execution assignee for follow-up comments until another Agent or Crew is selected or the Agent becomes unavailable.

See Agent task execution for the full lifecycle.

Instructions and context

Agent instructions are included in each run. Use them for stable behavior such as:

scope and role;

how to inspect a Task before acting;

when to ask for human input;

expected checks;

reporting format;

actions that require caution.

Put Task-specific requirements in the Task description or comments instead. Put a reusable procedure that several Agents may share in a Skill.

Computer and Runtime

The Agent's execution target combines a Computer connection with a Runtime provider detected on that Computer.

If the Computer is offline, new runs normally wait for it to reconnect. If the selected Runtime is no longer available, choose another eligible Runtime before expecting new work to run.

A single Computer can serve several Agents. Capacity is bounded by the Computer, Agent concurrency, and task-directory availability.

Task Working Directory

Agents support two working-directory modes:

Temporary: each Task gets an isolated directory. Repository-backed runs can prepare a fresh worktree, which supports safer parallel execution.

Specified: runs use one configured absolute local directory from the Agent's directory pool. This is available only for local Computers and reuses the code and tools already present there.

A specified directory can serve one run at a time. Configure multiple directories when that Agent must run several Tasks concurrently in specified mode. Invalid or unavailable paths cannot be used for a run.

Skills and repositories

Attach Skills for reusable operating knowledge. Local Runtime Skills remain available automatically on that Computer; shared Space Skills must be assigned to the Agent.

Attach repositories when this Agent needs a narrower code scope than the Space default. If no repositories are attached to the Agent, Sharkly uses the Git repositories configured for the Task's Space.

Run settings

Use Task Run Settings to control:

the maximum number of parallel running Tasks;

the maximum duration of a normal run;

the Task Working Directory mode and paths.

Higher concurrency consumes more CPU, memory, disk, provider capacity, and repository bandwidth. Increase it only after the current Computer and Runtime handle the existing workload reliably.

Status and activity

The Agent list and detail view can show availability, workload, recent runs, and archived state. Task runs have their own states, including queued, dispatched, waiting for a local directory, running, completed, failed, and canceled.

Agent availability and Task status are different. An online Agent may still have queued work because concurrency or directory capacity is full.

Archive an Agent

Archiving removes an Agent from assignment and mentions and cancels its running work. Its prior Tasks, comments, and run history remain available. Sharkly also supports restoring an archived Agent when it should become usable again.

Before archiving, check whether Automations or Crews still depend on the Agent.

What an Agent contains#

Create an Agent#

Visibility#

Assign Tasks to an Agent#

Instructions and context#

Computer and Runtime#

Task Working Directory#

Skills and repositories#

Run settings#

Status and activity#

Archive an Agent#