Skip to main content

Agents

An agent is a named, reusable set of instructions that Co-Scientist runs on your behalf in a Seqera Platform workspace. A Co-Scientist conversation is interactive and starts empty each time. An agent captures a task you repeat, such as investigating failed runs or summarizing results, and anyone in the workspace can run it without rewriting the prompt.

Agents are workspace-scoped. Every agent in a workspace is visible to everyone with permission to read agents, not only the person who created it. An agent acts as the service account bound to it rather than as the person who starts it, and reaches private repositories through a GitHub App credential in its workspace.

Agents are available in organization workspaces only. They are not available in a personal workspace.

Agents, chat, and coding agents​

Seqera uses the word "agent" for three different things:

  • Agents (this page): Reusable instruction sets you create in a workspace and run against pipeline runs.
  • Co-Scientist chat: The interactive assistant panel in Seqera Platform.
  • Coding agents: Third-party tools such as Claude Code or Codex that you connect to Seqera through a skill.

Agents are also unrelated to Tower Agent, the component that connects Seqera Platform to a high-performance computing (HPC) cluster.

Agents compared with Co-Scientist chat​

Agents and Co-Scientist chat are the same assistant reached two ways. Both work inside a Seqera Platform workspace and can read your runs and act on them. They differ in who they act as, who sees them, what starts them, and whether you can add to the conversation.

AgentCo-Scientist chat
Where it runsIn the background, once startedIn the Co-Scientist panel in Seqera Platform, while you watch
InstructionsWritten once and saved, reused on every runWritten fresh in each conversation
Acts asThe service account bound to the agentYou, with your own permissions
Who sees itEveryone in the workspace who can read agentsOnly you, in your own session
What starts itYou, from a run, or an action that targets the agentYou, by typing in the panel
ConversationRead-only. To add messages, fork it into a chat of your ownRead-write for the user who started it

Permissions​

Workspace grants decide who can see and manage agents. The service account bound to an agent decides what the agent can do when it runs.

Workspace grants​

Four workspace grants control access to agents:

GrantAllows
Agent_ReadView and search the workspace's agents
Agent_WriteCreate and edit agents, and pause or resume them
Agent_ExecuteRun an agent
Agent_DeleteRemove an agent

Agents appears in the navigation only for users with Agent_Read.

Agent identity and permissions​

An agent acts as a service account, not as the person who starts it. You must bind one. Select it under Agent permissions when you create or edit the agent. Every run of that agent uses that account's roles. Whoever starts the run, the agent reaches only what the service account can reach.

  • Only service accounts assigned to the agent's workspace can be bound. An account with no role in the workspace cannot act there.
  • The service account's workspace role must include Agent_Execute. Every built-in role except Connect and View includes it.
  • Service accounts belong to the organization. If none is assigned to your workspace, ask an organization owner to create one and assign it before you create the agent.
  • If the bound service account is later disabled, or its workspace role loses Agent_Execute, the agent's runs fail rather than fall back to the permissions of whoever started them.
  • You cannot remove the bound service account from the workspace, or delete it from the organization, while active agents use it. Seqera Platform lists those agents. Pause or remove them first.
caution

Scope the service account to what the agent's instructions need. Every run of the agent carries those permissions, whoever in the workspace starts it.

Access to private Git repositories​

An agent reaches a private repository only through a GitHub App credential. No other Git credential type works for an agent. A personal access token works elsewhere in Seqera Platform but not here.

Bind the credential to the agent under Agent permissions, alongside the service account. The credential is optional. An agent without one still runs and can clone public repositories, but cannot clone private repositories, commit, or push. With one bound, the agent can also clone private repositories, commit, and push, as that credential.

Before you can bind a credential:

  • A GitHub organization admin must install the GitHub App in the GitHub organization and grant it access to the repositories the agent needs.
  • The credential must exist in the workspace the agent runs in. Because credentials are workspace-scoped, an agent cannot use one from another workspace or from a user's personal credentials.

If a bound credential is later removed from the workspace or marked invalid, the agent form warns you and blocks saving until you select a different credential or clear it with None.

Create an agent​

To create an agent, you need Agent_Write.

  1. In your workspace, select AI > Agents.
  2. Select Add. If the workspace has no agents yet, select Add agent instead.
  3. Choose a starting point:
    • Fix failed runs, Summarize successful runs, or Summarize failed runs: A template that prefills the name, description, and instructions.
    • New agent: Write your own instructions.
  4. Complete the details:
    • Name (required): Letters, numbers, dashes, and underscores only.
    • Description (optional).
    • Agent instructions (required): What the agent does when it runs.
  5. Under Agent permissions:
  6. Save the agent.

Templates prefill text only. They do not set a trigger, a schedule, or where the agent runs. Review and edit the instructions before saving.

Manage agents​

The Agents page lists every agent in the workspace that you can read, with its status. From there you can:

  • Search for an agent by name.
  • Edit an agent's name, description, instructions, service account, and GitHub App credential. The template picker does not appear when you edit.
  • Pause an agent to keep its definition but remove it from the list of agents to run, and Resume it later. A paused agent shows as Inactive.
  • Remove an agent. Seqera Platform asks you to confirm.

Paused and removed agents do not appear when you select an agent to run. Removing an agent does not delete the sessions it already produced.

Run an agent​

Start an agent from a run. The agent works with that run's context. You need Agent_Read, Agent_Execute, and the chat:execute permission for Co-Scientist chat. Without chat access, Trigger agent does not appear.

To run an agent:

  1. Open the run, or find it in a project's Runs tab.
  2. Select Trigger agent.
  3. Choose an agent from the list. Search by name if the workspace has many.

The agent's session opens in the Co-Scientist panel, where you can follow what it does. Agent sessions are read-only. To continue the conversation as your own chat, select Fork conversation.

Only active agents appear in the list. If the workspace has no active agents, the list offers Add agent to users with Agent_Write.

Agent definition​

An agent holds a name, a description, its instructions, the service account it acts as, and an optional GitHub App credential. It does not carry a trigger, a schedule, a compute environment, or a sandbox configuration. Those are properties of how the agent is run, not of the agent itself. An agent that runs on an event is an agent selected as the target of an action, not a different kind of agent.

Learn more​

On this Page