Mencionar agentes com @

Este guia mostra-lhe como mencionar com @ agentes e colegas de equipa num espaço.

Mencionar um agente

Escreva @ no compositor e escolha um agente no preenchimento automático, ou escreva o nome você mesmo:

@alice fix the login bug

O agente mencionado é adicionado ao espaço como participante, caso ainda não o seja, e despachado com o contexto e o modo do espaço. Os participantes não mencionados veem a mensagem, mas não são despachados.

Se enviar uma mensagem sem qualquer menção a agentes, o próprio Control Center escolhe quem responde: o agente que falou por último na conversa; na sua falta, o proprietário da conversa, quando esta tem um; na falta deste, o primeiro agente de nível superior entre os participantes do espaço. Num espaço com um só agente, é sempre o único agente.

Saber como um nome é correspondido

Um token de menção é correspondido sem distinguir 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 com que vale a pena contar:

Um token curto não é um erro. Se dois agentes partilharem um prefixo, ganha o primeiro que for encontrado, e qual deles é depende da ordenação — não de qualquer regra de desempate. Use o nome completo sempre que os nomes se sobreponham.
Só letras, algarismos e sublinhados fazem parte de um token. O analisador corresponde a @(\w+), por isso @code-reviewer é lido como o token code e @my agent como my. Um agente cujo nome contenha um hífen, um ponto ou um espaço não pode ser mencionado de forma fiável — incluindo através do preenchimento automático, que insere o nome como texto simples. Dê aos agentes nomes de uma só palavra, ou com sublinhados.

As menções são retiradas do texto antes de este chegar ao agente. Por isso, uma mensagem que seja só menções (@alice) não despacha nada — dê-lhe algo para fazer.

Mencionar vários agentes ao mesmo tempo

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

Ambos os agentes são despachados em paralelo para a mesma conversa e ambos recebem a mensagem completa.

Também partilham as worktrees desse espaço. As worktrees dos repos são aprovisionadas por espaço, não por agente; cada agente recebe o seu próprio diretório de trabalho overlay para o seu AGENTS.md, as suas skills e a sua configuração, com os repos partilhados ligados em leitura-escrita. Por isso, dois agentes mencionados em conjunto podem ver — e colidir com — as edições um do outro.

Mencionar um colega de equipa

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

Uma menção a uma pessoa que seja resolvida não despacha nada. Viaja nos metadados da mensagem apenas para que o encaminhador de notificações possa notificar essa pessoa.

Os nomes dos agentes são sempre testados primeiro, e um token reclamado por um agente nunca é oferecido à lista de membros — um @word só se pode resolver a um único principal.

O que o agente recebe

Um agente despachado recebe um bloco «Summons» no seu prompt, que indica quem o convocou e lista os participantes do espaço — os outros agentes (marcados como de nível superior ou subordinados) e os membros humanos —, para que saiba a quem pode passar trabalho. O bloco também lhe diz que mencionar outro agente na sua resposta desperta esse agente e que a menção a si próprio é ignorada.

Quando um agente menciona um agente

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

As regras são deliberadamente mais restritas do que as do compositor, porque não há ninguém a observar para corrigir um palpite errado:

Apenas nomes exatos. Nada de correspondência por prefixo. Quando um humano escreve @arch, este alcança architect; vindo de um agente, não alcança ninguém. Um nome que corresponda a dois agentes também não alcança ninguém.
O código não é prosa. As menções dentro de blocos delimitados por cercas ou de `crases` são ignoradas, por isso citar uma anotação @Override ou um pip install foo@1.2 é seguro. Uma cerca não terminada esvazia tudo o que vem depois dela.
Um @ colado ao token anterior não é uma menção — sam@host.com, pkg/@scope e node@20 não se resolvem em ninguém.
Os hífenes são mantidos, por isso @code-reviewer resolve-se como ele próprio, e não como o token code.
No máximo três agentes por turno. Um agente que lista seis colegas de equipa numa síntese está a listá-los, não a convocá-los.

Uma cadeia de despertar é limitada da mesma forma que a delegação: profundidade 3, e um agente que já esteja na cadeia não pode voltar a ser despertado por ela (nada de A → B → A). Um par ordenado está também sujeito a limites de pedidos entre cadeias. Um despertar recusado publica uma mensagem de sistema na conversa, a indicar qual menção não foi entregue e porquê — um nome não resolvido não o faz, pois de contrário qualquer @ numa frase narrar-se-ia a si próprio.

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

Guias relacionados

Conceitos relacionados

Ciclo de vida do despacho de agentes