Mencionar agentes com @

Este guia mostra como mencionar agentes e colegas de equipe com @ em um espaço.

Mencionar um agente

Digite @ no composer e escolha um agente no autocomplete, ou digite o nome você mesmo:

@alice fix the login bug

O agente mencionado é adicionado ao espaço como participante, se ainda não for um, e despachado com o contexto e o modo do espaço. Participantes não mencionados veem a mensagem, mas não são despachados.

Se você enviar uma mensagem sem nenhuma menção a agente, o Control Center escolhe um respondedor por conta própria: o agente que falou por último na conversa, senão o proprietário da conversa quando ela tem um, senão o primeiro agente de nível superior entre os participantes do espaço. Em um espaço com um único agente, é sempre o único agente.

Como um nome é correspondido

Um token de menção é correspondido sem diferenciar maiúsculas de minúsculas, por nome exato ou prefixo. Assim, @arch alcança um agente chamado architect, e @Alice alcança alice.

Duas consequências que vale a pena considerar ao planejar:

Um token curto não é um erro. Se dois agentes compartilham um prefixo, o primeiro encontrado vence, e qual deles é depende da ordenação — não de uma regra de desempate. Use o nome completo sempre que os nomes se sobrepuserem.
Só letras, dígitos e sublinhados fazem parte de um token. O parser corresponde a @(\w+), então @code-reviewer é lido como o token code e @my agent como my. Um agente cujo nome contém um hífen, um ponto ou um espaço não pode ser mencionado de forma confiável — inclusive pelo autocomplete, que insere o nome como texto simples. Dê aos agentes nomes de uma só palavra, ou com sublinhados.

As menções são removidas do texto antes que ele chegue ao agente. Uma mensagem que é só menções (@alice), portanto, não despacha nada — dê a ela algo para fazer.

Mencionar vários agentes de uma vez

@alice refactor the auth module. @bob write tests for it.

Os dois agentes são despachados em paralelo na mesma conversa, e ambos recebem a mensagem completa.

Eles também compartilham as worktrees desse espaço. As worktrees de repos são provisionadas por espaço, não por agente; cada agente recebe seu próprio diretório de trabalho overlay para seu AGENTS.md, suas skills e sua configuração, com os repos compartilhados vinculados em leitura e escrita. Então dois agentes mencionados juntos podem ver — e colidir com — as edições um do outro.

Mencionar um colega de equipe

Qualquer @token que não corresponda a um agente é testado contra os membros humanos do espaço de trabalho, pelo handle, com a mesma regra de nome exato ou prefixo sem diferenciar maiúsculas de minúsculas.

Uma menção a humano resolvida não despacha nada. Ela viaja nos metadados da mensagem apenas para que o roteador de notificações possa avisar essa pessoa.

Os nomes de agentes são sempre testados primeiro, e um token reivindicado por um agente nunca é oferecido à lista de membros — um @word só pode ser resolvido para um único principal.

O que o agente recebe

Um agente despachado recebe um bloco “Summons” em seu prompt, nomeando quem o convocou e listando os integrantes do espaço — os outros agentes (marcados como de nível superior ou subordinados) e os membros humanos —, para que ele saiba a quem pode passar trabalho adiante. O bloco também diz a ele que mencionar outro agente na resposta desperta esse agente, e que mencionar a si mesmo é ignorado.

Quando um agente menciona um agente

Um agente pode passar trabalho adiante na própria resposta. Quando uma rodada termina de forma limpa, as menções em seu texto são resolvidas, e esses agentes são adicionados ao espaço e despachados na mesma conversa, com a rodada que os mencionou como prompt. Uma rodada que falhou ou foi interrompida não desperta ninguém — ela parou no meio do raciocínio.

As regras são deliberadamente mais rígidas que as do composer, porque não há ninguém observando para corrigir um palpite errado:

Somente nomes exatos. Nada de correspondência por prefixo. @arch alcança architect quando um humano o digita; vindo de um agente, não alcança ninguém. Um nome que corresponde a dois agentes também não alcança ninguém.
Código não é prosa. Menções dentro de blocos delimitados ou de `backticks` são ignoradas, então citar uma anotação @Override ou um pip install foo@1.2 é seguro. Um delimitador não fechado apaga tudo o que vem depois dele.
Um @ colado ao token anterior não é uma menção — sam@host.com, pkg/@scope e node@20 não se resolvem para ninguém.
Os hífens são mantidos, então @code-reviewer se resolve como ele mesmo, e não como o token code.
No máximo três agentes por rodada. Um agente que lista seis colegas de equipe em um resumo está listando-os, não os convocando.

Uma cadeia de despertar é limitada da mesma forma que a delegação: profundidade 3, e um agente que já está na cadeia não pode ser despertado de novo por ela (nada de A → B → A). Um par ordenado também está sujeito a limite de frequência entre cadeias. Um despertar recusado publica uma mensagem de sistema na conversa, dizendo qual menção não foi entregue e por quê — um nome não resolvido não publica, já que, de outro modo, qualquer @ em uma frase narraria a si mesmo.

Para uma transferência que não pode depender de prosa — uma solicitação/resposta, ou alcançar um agente fora do espaço —, use as ferramentas send_to_agent, ask_agent e delegate_task.

Guias relacionados

Conceitos relacionados

Ciclo de vida do despacho de agentes