Agents

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.

​

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, and a custom agent can also be given access to the web so it isn’t limited to what your workspace already knows.

​

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.

​

Working on notes and note templates

Open a saved note or saved note template and use the agent composer beside it. The subject chip identifies the exact note or template the chat is about. A new chat follows the item you have open; once you send a message, that chat keeps its subject even if you navigate elsewhere or reopen the chat later. Start a new chat to work on another item. On a note, ask the Superthread Agent to revise the enhanced notes with instructions such as “Group the actions by owner.” Asking it to use a different template regenerates an enhanced version from the original notes and transcript. The result streams into the note editor, and completion confirms it has been saved. A failed enhancement keeps the previous saved version. On an owned template, ask it to edit the meeting context or ordered sections. The updated template affects later enhancements; applying it again to an existing note is a separate request. The built-in agent uses your permissions. Only a note’s owner can revise or re-enhance it, and only a template’s owner can edit that template. Custom agents with a note read grant can read the note but cannot edit it or observe its enhancement operation. Shared or built-in templates you do not own remain read-only. The same operations are available through MCP and the CLI.

​

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.

​

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.

​

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.

​

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.

​

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.

​

Your notes

Add my notes gives a custom agent access to your own notes — the ones under My notes, including private ones. It’s what makes an agent that files actions from your meetings possible, and it’s the only way an agent can be set to run when a note is enhanced. Three things make this different from adding a space:

• You’re granting your own notes, nobody else’s. The grant covers your notes only. It never reaches another person’s, whatever access they have to the agent.
• A custom agent can read your notes, never change them. Only you can revise or re-enhance a note, through the built-in Superthread Agent acting as you.
• The grant stays yours. You can withdraw it at any time from the agent’s Share menu, even if you can’t otherwise edit the agent. People with full access can also remove it.

Superthread asks you to confirm before the grant is added, because of what it means once the agent is shared — see what sharing means for your private things.

​

Web access

By default an agent only knows what’s in your workspace. Web access lets it look outside — useful for an agent that researches competitors, checks a vendor’s docs, or summarises a page someone linked in a comment. Turn on Search and read the web and the agent gains two abilities together:

• It searches the web itself when a question needs something your workspace doesn’t hold.
• It reads pages linked in the conversation — a URL you paste, or one it found while searching.

Answers built from the web are cited: each passage shows the source it came from, so you can check a claim rather than take it on trust.

​

Limiting which sites

Sites decides where the agent may go:

• Any site — no restriction.
• Only these sites — an allowlist: those sites and nothing else.
• Every site except these — a blocklist: anything but those sites.

Enter one domain per entry, with no path — example.com, not example.com/docs. Subdomains are included automatically, so example.com also covers docs.example.com. You can paste a full URL and Superthread will keep the domain and drop the rest. The list covers searching and link-reading alike; an agent can’t reach through one what it’s blocked from on the other. If you choose Only these sites and list nothing, the agent can’t reach the web at all — Superthread warns you when that happens. Links to your own Superthread cards and pages are a special case: rather than fetching them from the public web, where they’d be just a sign-in page, the agent opens them through its normal workspace access. So a linked card is subject to what the agent can access, exactly like any other card it reads.

​

Gmail and Google Calendar

Web access lets an agent read the open web. Gmail and Google Calendar let it work in a Google account you connect to it — reading mail, drafting replies, finding a free slot, moving a meeting. Both live in the agent’s Access section, and both are set up per agent: connecting an account to one agent doesn’t give it to any other.

​

Connecting an account

Choose Connect, sign in to Google and grant access. The account then appears on the agent with its address and its current state. You can connect more than one account to the same agent, and an account you’ve already connected can be added to another agent without signing in again.

​

What the agent may do

Reading is always included: Gmail agents can read and search your mail, and Calendar agents can read your events. Everything that changes something is off until you turn it on. Require confirmation is on by default and is the safety net under all of it: the agent stops before it acts, shows you the actual email or event change it wants to make, and does nothing until you approve. Turn it off only for an agent whose work you’re happy to have happen unattended. Only the person who connected an account can change what it allows. Anyone else managing the agent sees the settings but can’t edit them.

​

Choosing calendars

A Google account usually holds several calendars. After connecting, pick which ones the agent can see, and mark one as the default — the calendar it books into when you ask for an event without saying where. The default has to be one of the calendars you’ve selected, and can’t be removed while it holds that role.

​

Running on mail and events

As well as answering you in chat, these agents can run on their own:

• A Gmail trigger runs the agent when mail arrives.
• A Calendar trigger runs it when events change, on whichever of the selected calendars you choose. Filters narrow this down — all-day events can be included, excluded or required, and you can restrict it to events you’ve accepted or declined.

Set both up under triggers, alongside the schedule and event triggers an agent already has.

​

Testing and disconnecting

Test in chat opens a conversation with the agent so you can check the connection does what you expect before you rely on it. If Google access is withdrawn — you revoke it in your Google account, or a password change invalidates it — the account shows as no longer connected and the agent stops using it. Reconnect restores it. Disconnect removes the account from that agent; it doesn’t touch your Google account or any other agent using 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.

​

What sharing means for your private things

An agent can hold things that belong to one person: a private space, a grant to someone’s notes, a connected Gmail or Google Calendar account. Sharing the agent shares the use of those things, and this is the part worth being deliberate about. Anyone who can use the agent can use what it holds. They can’t open your notes or your inbox directly, and they won’t see them listed anywhere — but they can ask the agent, and the agent will answer from them. An agent with your notes will summarise them for a colleague who asks. An agent with Send email turned on will send mail from your address when someone else tells it to. Superthread warns you on the Share menu when an agent holds private content, but the judgement is yours. Connecting is personal; using is shared. Only you can connect your Google account or grant your own notes, and only you can change what a connected account allows — anyone else managing the agent sees those settings but can’t edit them. What they can do is run the agent. You can always withdraw. Disconnect an account, or remove your notes grant, and the agent loses that access immediately. Your notes grant is yours to remove whatever your access to the agent itself. Disconnecting an account affects that agent only — not your Google account, and not another agent you’ve connected the same address to. Requiring confirmation limits the damage. With Require confirmation on, nothing leaves the agent unseen: it shows the email or the calendar change and waits for approval. Leaving it on is the difference between a shared agent that drafts on your behalf and one that acts on your behalf.

​

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.
• Keep web access as narrow as the job allows. Turn it on only for agents that need outside information, and prefer an explicit list of sites over the open web — it costs less and keeps the agent reading sources you trust.
• Give triggers focused prompts. A trigger prompt that says exactly what to do with the thing that just changed beats a general-purpose one.

​

Related

• 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
• Calendar integration – the read-only calendar connection used for meeting notes
• Plans and billing – workspace plans and billing