Skip to main content
An agent is an AI teammate that works inside your workspace. It can read and write the same things a person can — cards, pages, boards, comments — but only where you’ve given it access. You can chat with an agent, @ mention it in a comment, or set it to run on a schedule or when something happens in your workspace. There are two kinds:
  • Superthread Agent – the built-in agent every workspace gets. It acts as you, using your own permissions, and needs no setup.
  • Custom agents – agents you build yourself. Each one has its own identity, its own instructions, and its own access to your workspace.
Both cost AI credits when they run.
Agents are available to workspace owners, admins, and members. Guests and view-only guests can’t use agents at all — they can’t chat with the built-in agent, and they can’t see, create, or be given access to custom ones.

​
What an agent can do

An agent can do almost everything a regular Superthread user can. It can search your workspace, create and update cards, move them between statuses, boards, and sprints, set assignees, priorities, tags, and dates, write and edit pages, reply to comments, and work with projects and roadmaps. Treat it like a colleague rather than a chatbot: anything you’d ask a teammate to go and do in Superthread is usually something you can ask an agent to do instead. What a custom agent is actually allowed to touch is set by its access.

​
The Superthread Agent

Every workspace comes with Superthread Agent, ready to use with no setup. It works on your behalf, borrowing your permissions — so it sees exactly what you can see, and a colleague asking the same question gets an answer from their access, not yours. Your chats with it are private too: everyone shares the same built-in agent, but nobody can see anyone else’s chat history, and there’s no setting to change that. Its settings can’t be edited. If you want particular behaviour, shared chats, or permissions of its own, create a custom agent instead. If you’d rather work in Claude, ChatGPT, or another AI tool, the Superthread MCP server does much the same job — it connects those tools to your workspace and, like the built-in agent, acts as you with your own permissions.
Your workspace also has a built-in Superthread Forms agent, used by the forms portal to help people find and fill in the right form. It doesn’t respond to mentions.

​
Custom agents

A custom agent is one you build yourself, for the work your team actually does. Unlike the built-in agent, it’s a first-class member of your workspace with its own identity:
  • It acts as an independent user, so it appears as a member of spaces and shows up as the actor on the work it does — you can see at a glance which card an agent updated or which comment it wrote.
  • It has its own workspace role and its own list of spaces, so what it can reach is set once and applies to everyone who uses it. It does not borrow the permissions of whoever asked.
  • It has its own instructions, model, and triggers.
That independence is what makes custom agents useful for repeatable work: a triage agent, a release-notes writer, a standup summariser. Everyone gets the same behaviour from it, and it can run when nobody is watching.
Acting as an independent user doesn’t mean taking up a seat. Custom agents are never billed as workspace members, however many you create — the only thing they cost is the AI credits their runs consume.

​
Creating a custom agent

Open Agents in the sidebar and click New agent. You’ll be asked what you want the agent to do — describe it in plain language and Superthread will draft the agent’s instructions for you. From there you can fill in:
  • Name and icon – how the agent appears in mentions, in the sidebar, and as the actor on its work.
  • Description – a short blurb shown in the agent’s chat view, so people know what it’s for.
  • Instructions – what the agent should actually do (see below).
  • Model and effort – which model it runs on and how hard it thinks.
  • Access – what the agent can reach in your workspace.
  • Triggers – when it should run without being asked.
You can also just ask the built-in Superthread Agent to do it. Tell it what you want an agent for and it can create one, and it can update your existing agents too — handy for tweaking instructions or adding a trigger without opening the settings yourself.

​
Instructions

An agent’s instructions are its standing brief — the description of its job that it reads on every single run. This is where the agent’s real behaviour lives, so it’s worth spending time on. Instructions are stored as a page, which means you edit them in the normal Superthread editor with full formatting, and you can open them as a page in their own right. Click Edit instructions on the agent to open them. You don’t have to write them from scratch. The agent assistant beside the instructions can draft and refine them for you — tell it what you want the agent to do and it will write the brief. Good instructions usually cover:
  • What the agent is responsible for, and what it should leave alone.
  • The steps it should follow, in order.
  • The format you want its output in.
  • The edge cases where it should stop and ask rather than guess.
You need Can edit access to an agent to change its instructions.

​
Model and effort

Each custom agent picks its own model, from both Anthropic (Claude) and OpenAI (GPT). Alongside the model you choose an effort level, which controls how much the model thinks through a task before answering:
  • No thinking – fastest and cheapest, best for simple, mechanical work.
  • Low through Max – progressively more deliberate multi-step reasoning.
  • Default – lets the model decide, which is not the same as turning thinking off.
More thinking gives better results on complex work and costs more credits, so match the level to the job. A summariser rarely needs more than low; an agent that plans work across several boards benefits from more.
If you switch to a model that doesn’t support the effort level you’ve chosen, Superthread automatically uses the closest level that model does support.

​
What the agent can access

This is the “what can this agent reach?” side of an agent, configured in the Access section. It has two parts. Role decides whether the agent can change things:
  • Editor – can create and change things in the spaces it can access.
  • Viewer – can read, but never create or change anything.
Spaces decides where it can do that:
  • All open spaces – every space that everyone in the workspace can already see. You can still add specific private or view-only spaces on top.
  • Just the spaces you add – nothing except the spaces you list explicitly. Viewers always work this way.
Two things are worth knowing. First, an agent’s role can never exceed the role of the person managing it — you can’t create an agent that’s more powerful than you are. Second, if you set an agent to a restricted scope and then add no spaces, it can’t reach anything at all; Superthread warns you when that happens.
This is separate from the built-in Superthread Agent, which has no access of its own — it always acts with the permissions of whoever is talking to it.

​
Who can use the agent

Sharing is the other axis: not what the agent can reach, but who is allowed to use it. Click Share on an agent to set this. General access is the workspace-wide default, applied to everyone who hasn’t been given something more specific:
  • No access – the agent is private to the people you name.
  • Can use – anyone in the workspace can view and run it.
  • Can edit – anyone in the workspace can also change its settings.
People with access grants individuals more than the default:
  • Can use – view the agent and run it.
  • Can edit – also change its settings and instructions.
  • Full access – also manage sharing, other people’s access, and the agent’s role.
A person’s effective access is whichever is higher, their own grant or the workspace default — so a personal grant can only ever raise access, never take it away. Full access is only ever granted to named people, and an agent must always keep at least one person with full access.

​
Who can see the chats

By default, people see their own conversations with an agent. You can widen that with Can view everyone’s chats, either for a specific person or for everyone in the workspace. Full access always includes it.
This applies to custom agents only. Chats with the built-in Superthread Agent are always private to the person who had them.

​
Running an agent

There are four ways an agent runs.

​
Chat

Open the agent from the Agents section in the sidebar and start typing. Your conversations are saved and grouped by agent under Chats in the sidebar, so you can pick a thread back up later.

​
Mentions

Type @ and the agent’s name in a comment, and the agent will run and reply in the thread — the same way you’d mention a colleague. This is the quickest way to pull an agent into work that’s already happening: ask it to summarise a long discussion, draft acceptance criteria, or pick up a card. Mentions can be turned off per agent if you’d rather it only ran on demand or on its triggers.

​
On a schedule

Add a Recurring trigger to run the agent at a set time. Pick the days of the week, the time, and the timezone, and write the prompt the agent receives when it fires. A daily digest, a Monday morning sprint check, an end-of-week summary.

​
On a workspace event

Event triggers run the agent when something happens. Add them from Triggers on the agent. You can trigger on:
  • Comments – on a card, a project, or a page. You can narrow this to any card in a specific board, sprint, or roadmap.
  • Cards moving – a card added to or removed from a board or sprint, or an epic added to a roadmap.
  • Card properties changing – status, assignees, priority, tags, sprint, project, due date, start date, estimate, board, or list. You can watch one specific property and only fire when it changes to particular values.
  • Content being added – a page or board added to a space.
  • Form submissions – when someone submits a specific form, or any form.
Each trigger carries its own prompt, so one agent can behave differently depending on what woke it up. Triggers can be enabled and disabled individually, and you need to save a new agent before you can add triggers to it.

​
Disabling and archiving

Disabling an agent stops it running at all — it can’t be chatted with, mentioned, or triggered — while leaving everything about it intact. Only the agent’s owner can re-enable it. Archiving hides the agent and its runs, and disables its triggers. Archived agents aren’t gone: switch on Show archived in the agents list to find them, and unarchive to bring an agent and its runs back.

​
Seeing what an agent has done

Every run is recorded, and each one shows where it came from — Chat, Mentioned, or Triggered. Because a custom agent acts as itself, its work is attributed to it throughout the workspace, so you can trace any change an agent made back to the run that made it.

​
Best practices

  • Give the agent the narrowest access it needs. Start with Viewer and specific spaces, and widen only when the agent genuinely needs to write.
  • Be specific in the instructions. Vague briefs produce vague work. Say what “done” looks like and what format you want.
  • Start with mentions, then automate. Use the agent by hand until its output is consistently right, then add a trigger.
  • Match effort to the task. Don’t pay for deep reasoning on work that doesn’t need it.
  • Give triggers focused prompts. A trigger prompt that says exactly what to do with the thing that just changed beats a general-purpose one.
  • AI credits – what agent runs cost, and how to see where the spend is going
  • MCP – connect Claude, ChatGPT, and other AI tools to your workspace
  • Mentions – how @ mentions work elsewhere in Superthread
  • Forms – the forms portal and its built-in agent
  • Spaces – how space membership and visibility work
  • Plans and billing – workspace plans and billing