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 Computer.

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;
  • assigned Skills;
  • Agent-specific Git repositories;
  • plain and secret environment variables;
  • additional Runtime arguments;
  • Task Working Directory settings;
  • maximum parallel running Tasks and a per-Task timeout.

The Agent follows the Runtime’s default model. It does not promise or display a specific model name. Change models in the Runtime or Computer tool configuration, not on the Agent.

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. The Agent does not expose a model picker or thinking-depth control.

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.

Default concurrency:

  • Specified directories: default concurrency matches the number of configured directories.
  • Temporary directories: default concurrency is 50% of the Computer limit.

You can switch to a manual value. If the manual value is higher than the directory count, the product warns that writes may collide across tasks. The warning text follows the product UI.

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.

Restore an archived Agent

Open Agents, choose More, then open Archived Agents. Choose Restore for the Agent you want to use again.

After it is restored, the Agent returns to the list and can be assigned or mentioned again when its Space access and Runtime requirements are met.

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

Why is there no model picker?

Sharkly cannot reliably read the model a Runtime is actually using, so Agents follow that Runtime’s default model and do not show a model name. There is no thinking-depth control on the Agent either. To change models, update the Runtime or Computer tool configuration.