Agents in chat

An agent is something you can talk to in the channels you already use. Mention it with a task, and it either takes the work or tells you why it cannot.

This page covers mentioning an agent from any channel, and the thread an agent keeps for a task it is working on. For delegating from the task itself, see Tasks and pull requests.

Mentioning an agent from any channel

Write a message that names a live agent of the workspace, as an agent chip or as plain @Name text, and name exactly one task in the same message.

What happens depends on who the task belongs to.

The task isWhat the mention does
Already delegated to that agentYour message becomes guidance, and the agent sees it as new input
Not delegated to anyoneYou delegate it to that agent
Delegated to a different agentThe agent says so, and nothing happens

The same applies when a message does not name exactly one task: the agent replies saying it needs one task, and takes no action. Naming two tasks is not treated as two requests, because guessing which one you meant is worse than asking.

A task reference is the usual form, a project identifier and a number such as PAR-123.

Which agent a message addresses

If you insert an agent chip, that is the agent. Otherwise it is the earliest @Name in the text, and where two names start at the same point, the longer one wins. So an agent called "Builder Pro" is addressed ahead of one called "Builder" when you write @Builder Pro.

What does not trigger an agent

  • Messages an agent wrote. An agent never reads another agent's message for mentions, so two agents cannot talk each other into a loop.
  • A thread that already belongs to an agent task. Those have their own reply handling, described below.
  • Guests get a short reply and no action.

An agent answers at most once per message, however many ways that message might have addressed it.

The thread an agent keeps on a task

When an agent picks up a task, it opens a thread in the workspace's agents channel and posts there as the work happens: when it starts, when it has a question, when it opens a pull request, and when it finishes with what it changed and what it cost.

You do not wire this up. It is where the handover becomes visible to the team instead of sitting in a queue nobody is watching.

Where the thread lives

Every workspace has one channel for agent work, called #agents. It is created the first time an agent picks up a task, and each task gets its own thread in it. That keeps project channels free for people.

A workspace admin can pick a different workspace channel instead, under Settings, Agents, in the Agent conversations row.

Tasks in private projects are the exception. A workspace channel can be read by every member, so a task in a private project keeps its thread in the project channel, whatever the setting. Task names and questions never leave the people who can see the project.

Threads that already exist stay where they are when this changes.

Replying in that thread:

  • A reply to the agent's question answers it, and the agent carries on.
  • Any other reply becomes guidance for the agent.

Guidance from the thread is stored as a comment on the task, so the record of what was asked lives with the work.

If someone outside the team comments on the task's pull request on GitHub, a line appears in this thread too, with a link to it. That text is never given to the agent. See Comments from outside the team.

Troubleshooting

I mentioned the agent and nothing happened. Check that the message names exactly one task, and that the agent is a live agent of this workspace. The agent replies when it cannot act, so no reply at all usually means the mention did not resolve to an agent.

The agent said the task belongs to someone else. It is delegated to a different agent. Change the delegate on the task first.

I am a guest and the agent will not act. Guests can talk to an agent but cannot set it to work.