Times de Agents

Times de agents permitem agrupar agents relacionados e habilitar transferências controladas entre eles (handoff). O time define o escopo de handoff: agents só podem transferir conversas para outros membros do mesmo time.

Visão geral

• Time — agrupamento administrativo de agents. Criado e gerenciado no Admin.
• Membership — declarada no agent/config.yml de cada agent (campo team_id). A esteira de sync aplica a membership na plataforma.
• Handoff — transferência de conversa entre agents do mesmo time. Configurado no agent/config.yml (campo handoff, com chaves agent_id UUID do destino).

Divisão de responsabilidades:

Ação	Admin	config.yml + sync
Criar time	Sim	Não
Excluir time	Sim	Não
Consultar team_id / agent_id	Sim	Não
Associar agent ao time	Não	Sim (team_id)
Remover agent do time	Não	Sim (team_id: null)
Configurar handoff	Não	Sim (chaves = agent_id destino)

---

Pré-requisitos

1. Time criado no Admin em Agents → Times de agents.
2. team_id do time copiado da listagem (chip copiável).
3. agent_id de cada membro disponível no detalhe do time (chip copiável).
4. Agent em modo GitHub com agent/config.yml configurado.

---

Configurando membership

Adicione team_id ao agent/config.yml após o campo handoff:

# UUID do time ao qual este agent pertence.
# Ausência = não altera membership atual.
# null = remove membership.
# UUID = associa/move para este time.
team_id: "550e8400-e29b-41d4-a716-446655440000"

Semântica do campo:

Valor no YAML	Efeito após sync
Campo ausente	Membership não alterada
team_id: null	Remove membership (agents.team_id = NULL)
team_id: <UUID>	Associa ao time; move implicitamente se já pertencia a outro

Movimento implícito

Ao declarar um team_id diferente do atual, o agent é movido para o novo time sem necessidade de team_id: null intermediário. O sync emite aviso identificando o time de origem e destino.

---

Configurando handoff

handoff é um mapa onde cada chave é o agent_id (UUID) do agent de destino — não o nome.

handoff:
  # Agent de suporte — recebe com state completo
  "550e8400-e29b-41d4-a716-446655440001":
    include_state: true
    include_memory: false
    additional_instruction: "O cliente já passou pela triagem. Foque no problema técnico."

  # Agent de fechamento — recebe apenas chaves específicas do state
  "550e8400-e29b-41d4-a716-446655440002":
    include_state:
      keys_filter: ["protocolo", "conta_id"]
    include_memory: false
    additional_instruction: null

Campos de HandoffTargetConfig

Campo	Tipo	Descrição
include_state	bool ou {keys_filter: [...]}	true = preserva todo o state; false = limpa; objeto = preserva apenas as chaves listadas
include_memory	bool ou {keys_filter: [...]}	Mesmo comportamento, aplicado à memória
additional_instruction	string ou null	Instrução extra enviada ao agent destino ao receber a transferência

Onde encontrar os UUIDs

• team_id: listagem de times em Admin → Agents → Times de agents (chip copiável na tabela).
• agent_id dos destinos de handoff: detalhe do time → tabela de membros (chip copiável na coluna Agent ID).

---

Ciclo de vida da membership

Agents em modo GitHub

1. Declare team_id e handoff no agent/config.yml e faça push.
2. A esteira de sync chama PATCH /admin/agent/{agent_id} com team_id no payload.
3. O backend salva agents.team_id e atualiza o snapshot DEV automaticamente via create_or_update_dev_version.
4. A membership efetiva no DEV é agents.team_id após o sync.

Conversas DEV abertas durante o sync

Uma conversa DEV já aberta no momento do sync continua exibindo o team_id anterior até ser reaberta. Isso é intencional e consistente com o comportamento dos demais campos. Feche e reabra a conversa para refletir a membership atualizada.

HOMOL e PROD

agent_version dos tipos HOMOL e PROD são snapshots históricos — preservam o team_id do momento da publicação e nunca são alterados por operações de membership. Isso garante rastreabilidade e reprodutibilidade dos ambientes publicados.

---

Excluindo um time

Pré-condições

A exclusão é bloqueada (409) se existir qualquer agent_version onde:

• team_id = <id do time>
• version_type IN ('PROD', 'HOMOL')
• deleted_at IS NULL

Agents soft-deletados e versões DEV não bloqueiam a exclusão.

Efeito da exclusão

1. agents.team_id é nullado para todos os agents ativos do time.
2. O time recebe deleted_at = now() (soft-delete).
3. agent_version (DEV, HOMOL, PROD) não são alteradas — snapshots preservados.

Efeito no config.yml após exclusão

Qualquer config.yml que ainda declare o team_id excluído falhará na próxima rodada da esteira com erro de validação (team_id <UUID> not found). Antes do próximo sync, remova ou nule o team_id no YAML de cada agent afetado:

# Remover membership após exclusão do time:
team_id: null

---

FAQ / Erros comuns

team_id inexistente no sync

422 Unprocessable Entity — team_id <UUID> not found

Causa: UUID referenciado não existe ou o time foi excluído.
Solução: crie o time no Admin ou corrija o UUID no YAML.

Handoff rejeitado por agent de outro time

422 Unprocessable Entity — agent <UUID> does not belong to team <UUID>

Causa: o agent_id destino no handoff pertence a um time diferente do agent de origem.
Solução: mova o agent destino para o mesmo time, ou ajuste o handoff para referenciar apenas membros do mesmo time.

Time bloqueado na exclusão

409 Conflict — Team has agents with PROD or HOMOL versions

Causa: existe agent_version com version_type IN ('PROD', 'HOMOL') associada ao time.
Solução: despublique (ou soft-delete) os agents com versão PROD/HOMOL antes de excluir o time.

team_id malformado

422 Unprocessable Entity — invalid UUID format

Causa: o valor em team_id ou em uma chave de handoff não é um UUID válido.
Solução: copie o UUID diretamente da interface administrativa (chip copiável) para evitar erros de digitação.

Agent exibe team_id desatualizado no DEV

Causa: conversa DEV aberta antes do sync.
Solução: feche e reabra a conversa DEV.