Como o ElevenAgents Architect funciona
O que o ElevenAgents Architect sabe quando uma conversa começa, como ele investiga e como transforma uma pergunta em uma alteração validada.
Visão geral
Uma conversa com o ElevenAgents Architect funciona como uma conversa do ElevenAgents em tempo real, no mesmo mecanismo que alimenta os agentes que você cria. As ferramentas do Architect são executadas no seu navegador, na sua sessão conectada. Cada ferramenta chama as mesmas APIs do ElevenAgents usadas pelo dashboard, portanto, todas as leituras e gravações são verificadas de acordo com suas próprias permissões. Consulte Permissões, aprovações e rascunhos.
O que o ElevenAgents Architect sabe por padrão
No início de cada conversa, o Architect recebe:
- Sua conta e workspace: seu plano, workspace e uso.
- Onde você está: a página e, quando você está dentro de um agente, esse agente e a ramificação que está aberta. Na barra lateral, o Architect também recebe uma captura da página e uma atualização antes de cada mensagem caso a página tenha mudado.
- Um resumo do agente: criado pela ElevenLabs quando você está dentro de um agente. Ele abrange o nome e o proprietário do agente, suas ramificações e a divisão de tráfego entre elas, o volume de chamadas dos últimos 7 dias, o estado do rascunho, os agentes conectados, os procedimentos, se há testes configurados e quais ramificações você pode editar.
- Contexto do agente: o documento
agents.mddo agente, compartilhado com todas as pessoas que criam o agente. Consulte Personalizando o Architect. - Suas preferências: seu documento pessoal
user.md, que se aplica a todos os agentes que você cria. - O que o ponto de entrada informou: por exemplo, os testes com falha, o resultado do Spotlight ou o problema. Consulte Iniciando uma conversa.
- Mensagens anteriores neste chat.
O Architect não começa com a configuração completa do agente, suas transcrições, resultados de testes, dados do Spotlight ou suas outras conversas com o Architect. Ele lê essas informações com ferramentas quando a tarefa precisa delas. Isso mantém cada conversa focada e significa que o Architect sempre trabalha com dados atuais, em vez de uma cópia desatualizada.
Investigações e instruções diretas
O Architect lida de forma diferente com dois tipos de solicitação.
Instruções diretas indicam a alteração, por exemplo, “Adicione uma proteção que bloqueie discussões sobre preços de concorrentes” ou “Deixe a primeira mensagem mais curta”. O Architect lê a configuração relevante, faz a edição e informa o que preparou. No modo de aprovação padrão, as edições na configuração do agente são preparadas em um rascunho sem pedir confirmação. Ações que afetam o tráfego ativo ou recursos compartilhados aguardam sua aprovação.
Investigações fazem uma pergunta sem indicar uma solução, por exemplo, “Por que as chamadas sobre reembolso estão sendo escaladas?” ou “Como posso melhorar as resoluções de reembolso?”. O Architect pesquisa antes de alterar qualquer coisa:
- Ele cria uma lista de tarefas para a investigação, que permanece visível acima do campo de mensagem à medida que os itens são concluídos.
- Ele começa com sinais de baixo custo, como contagens de conversas, tópicos e resultados de avaliação, antes de ler transcrições individuais.
- Ele analisa conversas em paralelo e agrupa o que encontra por causa raiz.
- Seu raciocínio fica visível. Cada etapa de raciocínio é recolhida como Pensamento por Ns e pode ser expandida.
- Ele informa o que encontrou, incluindo quantas conversas realmente leu. Ele não apresenta uma amostra como se fosse exaustiva.
Modo de plano
Para alterações maiores, mude o campo de mensagem para Plano (pressione Shift+Tab para alternar entre os modos). No modo de plano, o Architect pesquisa usando ferramentas somente de leitura, cria um plano que você pode acompanhar enquanto ele é elaborado e então pede que você Aprove o plano ou Rejeite. Ele não faz nenhuma alteração até que você aprove. Se você rejeitar o plano com uma observação, o Architect o revisa e pergunta novamente.
Na aba do Architect em tela cheia, o plano aparece em um painel acima do campo de mensagem. Na barra lateral, ele aparece como um cartão no chat.
Exemplo prático: melhorando resoluções de reembolso
Este exemplo acompanha uma única conversa, de uma pergunta ampla até uma alteração pronta para revisão. Os nomes das ferramentas são exibidos para que você possa relacionar cada etapa ao que aparece na conversa. O Architect escolhe suas próprias etapas, portanto, uma conversa real pode diferir em ordem e detalhes.
A solicitação, enviada pela aba Architect do agente:
Como posso melhorar as resoluções de reembolso?
Planejar a investigação
O Architect cria uma lista de tarefas (write_todos): medir o problema, encontrar conversas de
reembolso com falha, identificar as causas raiz, propor e testar uma correção.
Medir o problema
O Architect lê os tópicos do agente (get_agent_topics, get_topics_summary) para encontrar o tópico de
reembolso e sua taxa de sucesso, depois conta e lista conversas recentes sobre reembolso que falharam na
avaliação (count_conversations, list_conversations).
Ler as conversas
O Architect pesquisa nas transcrições por solicitações de reembolso (search_conversation_messages,
semantic_search_conversations) e analisa em paralelo um lote de conversas com falha
(analyze_conversation_subagent). Cada análise informa o que o usuário queria, onde o agente
errou e o turno em que isso aconteceu.
Encontrar a causa raiz
O Architect compara as falhas com a configuração atual (get_agent_config,
list_procedures, get_procedure). Ele relata uma descoberta como: “Em 31 de 40 chamadas de reembolso
com falha, o agente chamou lookup_order antes de pedir o número do pedido, recebeu um erro e
escalou a chamada.”
Fazer a alteração em uma ramificação
O Architect cria uma ramificação (create_branch) para que a alteração fique isolada do agente ativo. Em
seguida, ele edita o procedimento de reembolso (update_procedure) para pedir o número do pedido antes da
consulta. A edição é preparada no seu rascunho nessa ramificação. Nada mudou para quem liga para o agente ativo.
Escrever testes para a alteração
O Architect escreve testes que registram a falha: uma simulação de alguém pedindo um reembolso
sem informar um número de pedido (create_simulation_test), um teste de chamada de ferramenta verificando se
lookup_order não é chamado primeiro (create_tool_test) e um teste gerado a partir de uma das
conversas reais com falha (generate_test_from_conversation). O Architect simula ferramentas que têm
efeitos colaterais nas simulações, portanto, nenhum reembolso real é emitido.
Executar os testes antes e depois
O Architect executa os testes no agente sem a alteração (run_tests na ramificação original
ou run_agent_tests com include_draft: false) e, em seguida, no rascunho com a
alteração (run_agent_tests), e lê os resultados (get_test_suite_summary,
get_test_suite_failures). O resultado esperado é que os novos testes falhem sem a alteração
e passem com ela. Se os testes continuarem falhando, o Architect lê as falhas, ajusta a alteração e
os executa novamente.
Apresentar a alteração
O Architect resume a causa raiz, a alteração e os resultados dos testes e abre a caixa de diálogo de
publicação (request_draft_publish). Você revisa o diff e seleciona Publicar, o que confirma a
alteração como uma nova versão na ramificação. O Architect não pode publicar por você.
Abrir uma proposta
O Architect lê o histórico e a prévia de merge da ramificação (get_branch_history,
merge_branch_preview) e abre uma proposta de merge em main (create_merge_proposal). A
descrição tem três seções, Resumo, Testes e Como revisar, escritas a partir dos
commits e execuções de teste reais. O Architect pode sugerir revisores
(suggest_merge_proposal_reviewers), mas você os escolhe.
A validação acontece dentro da conversa, antes de você ser solicitado a publicar ou revisar qualquer coisa. Quando a proposta chega a um revisor, os testes que motivaram a alteração já estão anexados ao agente e foram executados na ramificação. Consulte Propostas e validação para saber o que o revisor vê.
A execução de testes antes e depois é uma boa prática, mas o Architect não a executa automaticamente em todas as alterações. Para garantir que ele faça isso, peça diretamente, por exemplo: “Mostre os novos testes falhando na main e passando na ramificação.”
Comandos de barra
Digite / no campo de mensagem para ver os comandos disponíveis na página atual.
A maioria dos comandos só se aplica quando você está dentro de um agente. /clear e /feedback não estão disponíveis na página inicial da aba Architect.
Dashboards no chat
O Architect pode criar um dashboard na conversa para responder a uma pergunta com dados, por exemplo: “Divida as escaladas desta semana por motivo e mostre a tendência”. Use /dashboard ou peça um diretamente.
O Architect reúne os dados com suas ferramentas, organiza-os com código e renderiza um dashboard feito com os mesmos blocos de métricas, gráficos, listas e cartões de texto do Spotlight. Um dashboard pode incluir:
- Blocos de métricas com um valor principal, variação e minigráfico.
- Gráficos: área, linha, barra, área empilhada, rosca e listas de barras classificadas para detalhamentos dos N principais.
- Listas com rótulos de status, datas e links para páginas no ElevenAgents, como conversas individuais.
- Cartões de texto com descobertas e recomendações.
Na aba do Architect em tela cheia, os dashboards são renderizados em linha na conversa. Na barra lateral, eles são abertos em um painel ao lado do chat.
Os dados do dashboard são mantidos somente na memória da aba do navegador em que foi criado e nunca são salvos com o chat. Depois que você recarrega a página, abre o chat em outra aba ou cria vários dashboards grandes, um dashboard mais antigo exibe uma mensagem em vez dos dados. Peça ao Architect para recriá-lo. Dashboards são capturas somente de leitura. Eles não têm filtros nem são atualizados em tempo real.
Executando código
O Architect pode executar programas curtos em Python para contar, agrupar e comparar dados de suas ferramentas, por exemplo, para calcular taxas de resolução por semana em algumas centenas de conversas. O código é executado em uma sandbox no seu navegador apenas com a biblioteca padrão do Python. Ele não tem acesso à rede, à sua conta da ElevenLabs e tem um limite de tempo de 20 segundos. A execução de código está sendo disponibilizada gradualmente e pode não estar disponível em todos os workspaces.
Respostas grandes
Quando uma ferramenta retorna mais dados do que cabem na conversa, como uma lista longa de conversas, o Architect mantém a resposta completa na memória da aba do navegador e trabalha com um resumo. Ele pode pesquisar e ler o restante quando necessário. Um aviso na chamada da ferramenta mostra quando isso aconteceu. Essas respostas nunca são salvas ou enviadas.